docs/quick-start.md

빠른 시작: Welley 최소 배포

Linux 호스트 한 대에서 Welley 인스턴스를 가장 빠르게 실행하는 방법이에요. 어떤 클라우드에서도, 직접 마련한 장비에서도 쓸 수 있어요. CLI가 실제로 요구하는 플래그만 쓰고, 나머지는 모두 기본값 그대로 둬요.

설치하면 이렇게 구성돼요: 플랫폼, RAG 파이프라인, Nginx, Redis, 그리고 함께 제공되는 PostgreSQL 컨테이너가 설치되고, 설치 중에 Let's Encrypt 인증서가 발급돼요. 관리형 데이터베이스, CDN, 텔레메트리, Slack 연동은 포함되지 않아요. 이런 구성은 AWS EC2와 DigitalOcean 가이드를 참고해 주세요.

1. 준비물

Linux 호스트

  • Ubuntu 24.04 LTS (또는 비슷한 최신 배포판).
  • 시작 사양은 2 vCPU, RAM 4GB, 디스크 60GB예요.
  • 바뀌지 않는 공개 IPv4 주소.
  • 인터넷에서 들어오는 TCP 80과 443, 그리고 내가 접속할 수 있는 22를 열어 두세요. 80번 포트는 설치 중 인증서 확인에 필요하고, 설치 후에는 매주 하는 갱신에 필요해요.
  • sudo 권한이 있는, root가 아닌 사용자가 필요해요. 이 가이드는 모든 작업을 그 사용자로 실행하고, 아래에서는 <user>라고 불러요.

DNS

호스트의 공개 IP를 가리키는 레코드가 두 개 필요해요.

레코드 용도
<domain> 사이트 자체
storage.<domain> 업로드 파일과 정적 파일 (이 구성에는 CDN이 없기 때문이에요)

시작하기 전에 먼저 만들어 두세요. CLI는 두 이름이 모두 이 호스트로 연결되는지 확인하고, 그렇지 않으면 멈춰요.

이메일 DNS 레코드

--smtp-from 주소의 도메인에는 이메일 인증 레코드가 필요해요. 이 레코드가 없으면 Gmail, Outlook 같은 대형 서비스는 지금까지 메일을 받아 본 적 없는 수신자에게 가는 메일을 버리는 경우가 많아요. 초대 메일과 가입 확인 메일이 모두 여기에 해당해요. 메일은 스팸함에도 들어가지 않는데, SMTP 제공업체에서는 발송됐다고 나와요.

레코드 유형 값
<mail-domain> TXT SPF, 예: v=spf1 include:<provider> ~all. 정확한 값은 SMTP 제공업체에서 확인하세요
_dmarc.<mail-domain> TXT DMARC, 예: v=DMARC1; p=none; rua=mailto:dmarc@<mail-domain>
<selector>._domainkey.<mail-domain> TXT 또는 CNAME DKIM, 도메인을 인증할 때 SMTP 제공업체가 생성해요

도메인에는 SPF 레코드를 하나만 둘 수 있어요. 이미 있다면 두 번째를 만들지 말고, 거기에 제공업체를 추가하세요. create는 SPF나 DMARC가 없으면 경고를 보여 주지만, 멈추지는 않아요. DKIM은 셀렉터 이름이 제공업체마다 달라서 확인할 수 없어요.

DKIM은 건너뛰지 마세요. Amazon SES를 비롯한 많은 제공업체는 기본적으로 자기 도메인을 엔벨로프 발신자로 해서 메일을 보내요. 그러면 SPF는 내 도메인이 아니라 제공업체의 도메인을 확인하기 때문에 DMARC 통과에 반영되지 않고, DMARC를 통과시킬 수 있는 건 DKIM뿐이에요. DKIM 상태는 제공업체의 콘솔에서 확인하세요. Amazon SES에서는 Verified identities 아래 <mail-domain>의 DKIM 항목에서 볼 수 있고, Successful로 표시되어야 해요. SES Easy DKIM은 <token>._domainkey.<mail-domain>이라는 이름의 CNAME 레코드 세 개를 게시해요.

SMTP 정보

호스트, 사용자, 비밀번호, 보내는 사람 주소가 필요하고, 어느 제공업체든 괜찮아요. 플랫폼이 이메일 확인과 비밀번호 복구에 이 정보를 쓰기 때문에, 없으면 CLI가 설치를 진행하지 않아요. 기본값은 587번 포트에서 STARTTLS로 메일을 보내는 방식이에요.

관리자 이메일 주소는 첫 로그인과 비밀번호 복구에 쓰여요.

2. Docker 설치

사용 중인 배포판의 공식 안내를 따라 주세요: Install Docker Engine. 그다음 내 사용자가 데몬을 사용할 수 있게 해요.

sudo usermod -aG docker <user>

로그아웃했다가 다시 로그인한 뒤, 두 가지가 모두 준비됐는지 확인해요.

docker ps
docker compose version

3. CLI 내려받기

호스트에 맞는 platform 값을 골라 주세요.

linux/amd64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/amd64" -o wlycli
chmod +x wlycli
./wlycli -v
linux/arm64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/arm64" -o wlycli
chmod +x wlycli
./wlycli -v
darwin/arm64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/arm64" -o wlycli
chmod +x wlycli
./wlycli -v
darwin/amd64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/amd64" -o wlycli
chmod +x wlycli
./wlycli -v

4. 배포

./wlycli deploy create \
-d example.com \
-e admin@example.com \
--smtp-host smtp.example.com \
--smtp-user "$MAIL_USER" \
--smtp-password "$MAIL_PASSWORD" \
--smtp-from noreply@example.com

이 여섯 개 플래그가 필수 항목의 전부예요. 이 명령은 DNS를 확인하고, 배포 파일을 만들고, Certbot으로 인증서를 발급받고, 컨테이너를 시작해요. 몇 분 정도 걸려요.

여기서 그대로 받아들이는 기본값은 다음과 같아요.

설정 기본값
설치 디렉터리 ~/.welley/<project>. <project>는 도메인에서 영문자와 숫자가 아닌 문자를 모두 _로 바꾼 값이에요 (example.com은 example_com이 돼요)
데이터베이스 함께 제공되는 PostgreSQL 컨테이너, 데이터는 설치 디렉터리 아래에 저장돼요
인증서 Certbot으로 받는 Let's Encrypt, 일주일에 한 번 자동으로 갱신돼요
업로드 파일과 정적 파일 https://storage.<domain>에서 제공돼요
업데이트 stable 채널, 매일 확인하고, 가능하면 중단 없이 적용돼요

5. 첫 로그인

생성된 관리자 비밀번호는 플랫폼 로그에 출력돼요.

docker logs example_com-platform-blue-1 | grep "Auto-init complete"

https://<domain>을 열고, -e로 넘긴 관리자 이메일로 로그인한 다음 바로 비밀번호를 바꾸세요. 바꾸기 전까지는 이 로그를 비밀로 다뤄 주세요.

6. 결과 확인

docker ps

nginx, platform-blue, rag-pipeline-blue, postgres, redis, autoheal, snoopy 컨테이너가 하나씩 보여야 해요. 이름은 모두 <project>-<service>-1 형식이에요.

문제가 생겼을 때

프로젝트 디렉터리나 그 컨테이너가 남아 있으면 create는 다시 실행되지 않아요. 파일은 괜찮고 일부 컨테이너만 시작되지 않았다면, 아무것도 잃지 않고 컨테이너를 다시 만들 수 있어요.

./wlycli deploy restart -d example.com

배포 자체를 다시 해야 한다면 삭제한 뒤 처음부터 시작하세요. 이 명령은 함께 제공되는 데이터베이스를 포함해 모든 것을 삭제해요.

./wlycli deploy delete -d example.com --yes-please-delete-all-the-data

다른 문서