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](https://docs.docker.com/engine/install/). 그다음 내 사용자가 데몬을 사용할 수 있게 해요.

```
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
```

## 다른 문서

-   [**Welley CLI** docs/index.md](https://welley.com/ko/administrators/docs/cli/)
-   [**서버 배포** skills/deploy-server/SKILL.md](https://welley.com/ko/administrators/docs/deploy-server-skill/)
-   [**openai.yaml** skills/deploy-server/agents/openai.yaml](https://welley.com/ko/administrators/docs/deploy-server-openai-yaml/)
-   [**DigitalOcean 참고 자료** skills/deploy-server/references/digitalocean.md](https://welley.com/ko/administrators/docs/deploy-server-digitalocean/)