관리자

# 내 Welley 서버 운영하기

저희 명령줄 도구는 Linux 머신 한 대에 Welley에 필요한 모든 것을 설치해요. 클라우드 서버에서도, 직접 갖춘 하드웨어에서도 쓸 수 있어요.

[읽기: 빠른 시작: 최소 Welley 배포](https://welley.com/ko/administrators/docs/quick-start/) [읽기: Welley CLI](https://welley.com/ko/administrators/docs/cli/) [Docker Engine 설치](https://docs.docker.com/engine/install/)

앞으로 Welley를 오픈 소스로 공개할 계획이에요. 공개 일정과 라이선스는 아직 발표되지 않았어요.

## 호스트, DNS, 이메일 준비하기

빠른 시작 가이드에 나온 기본 요구 사항이에요. 필요한 용량은 사용자 수와 작업량에 따라 달라요.

### Linux 호스트

-   Ubuntu 24.04 LTS 또는 비슷한 최신 배포판이에요.
-   vCPU 2개, RAM 4GB, 디스크 60GB로 시작하세요.
-   고정 공개 IPv4 주소와, sudo를 쓸 수 있고 root가 아닌 사용자를 사용하세요.

### 네트워크

-   인터넷에서 들어오는 TCP 80, 443을 허용하세요. TCP 22는 내 네트워크에서 들어오는 연결을 허용하세요.
-   80번 포트는 인증서 확인과 주간 인증서 갱신을 위해 비워 두세요.

### 사이트 DNS

-   내 도메인과 storage.<domain>이 호스트의 IP 주소를 가리키게 하세요.
-   설치하기 전에 두 레코드를 모두 만드세요. CLI가 레코드를 확인하고, 호스트로 연결되지 않으면 멈춰요.

### SMTP와 관리자 이메일

-   SMTP 호스트, 사용자, 비밀번호, 보내는 주소를 준비하세요. 기본값은 587번 포트의 STARTTLS예요.
-   처음 로그인하고 비밀번호를 복구할 때 쓸 관리자 이메일도 필요해요.

### 이메일 DNS

-   보내는 주소의 도메인에 SPF, DMARC, 이메일 제공자가 만들어 주는 DKIM을 설정하세요.
-   이메일 제공자가 알려 준 SPF 값을 그대로 사용하세요. 두 번째 SPF 레코드를 추가하지 말고 기존 SPF 레코드에 합치세요.
-   SPF나 DMARC가 없으면 CLI가 경고해요. 이메일 제공자의 DKIM 셀렉터는 확인하지 못해요.

## Docker Engine과 Compose 설치하기

사용 중인 Linux 배포판에 맞는 Docker 공식 안내를 따르세요. 그다음 배포용 사용자가 Docker를 쓸 수 있게 하세요.

[Docker Engine 설치](https://docs.docker.com/engine/install/)

### 사용자를 Docker 그룹에 추가하기

<user>를 root가 아닌 배포용 사용자로 바꾸세요. 이 명령을 실행한 뒤에는 로그아웃했다가 다시 로그인하세요.

```
sudo usermod -aG docker <user>
```

### Docker와 Compose 확인하기

그 사용자로 두 명령이 모두 동작해야 해요.

```
docker ps
docker compose version
```

## CLI 내려받기

CLI를 실행할 머신에 맞는 바이너리를 고르세요. 배포 호스트 자체는 Linux여야 해요.

### Linux, x86-64

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

### macOS, Apple silicon

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

### macOS, Intel

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

-   이 명령은 안정 채널에서 내려받고 CLI 버전을 보여 줘요.
-   버전은 새 릴리스마다 바뀌어요. 설치할 때는 최신 CLI 문서를 참고하세요.

## 배포 만들기

준비한 Linux 호스트에서 이 명령을 실행하세요. 예시의 도메인, 이메일, SMTP 값은 내 값으로 바꾸세요.

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

| 설정 | 기본값 |
| --- | --- |
| 설치 디렉터리 | ~/.welley/<project>예요. 예시 도메인의 경우 프로젝트 이름은 example\_com이 돼요. |
| 데이터베이스 | 번들 PostgreSQL이고, 데이터는 설치 디렉터리 아래에 저장돼요. |
| 스택 | Welley 플랫폼, RAG 파이프라인, Nginx, Redis, PostgreSQL과 유지 관리용 컨테이너예요. |
| 인증서 | Certbot을 통한 Let’s Encrypt이고, 매주 갱신돼요. |
| 미디어 | 업로드 파일과 정적 파일은 https://storage.<domain>에 있어요. |
| 업데이트 | 안정 채널이고, 매일 확인해요. 업데이트 과정에서는 가능한 한 중단 시간이 생기지 않게 해요. |
| 선택 서비스 | 최소 설정에는 관리형 데이터베이스, CDN, 텔레메트리, Slack 연동이 포함되지 않아요. |

-   실행하기 전에 MAIL\_USER와 MAIL\_PASSWORD를 SMTP 자격 증명으로 설정하세요.
-   빠른 시작 가이드에서는 이 플래그 여섯 개가 필요해요.
-   이 명령은 DNS를 확인하고, 배포 파일을 쓰고, Certbot으로 인증서를 받고, 컨테이너를 시작해요.
-   deploy 명령은 deployment의 별칭이에요.

## 로그인하고 결과 확인하기

생성된 관리자 비밀번호는 플랫폼 로그에 있어요. 그 출력은 공개하지 마세요.

### 초기 비밀번호 찾기

이 컨테이너 이름은 example.com 기준이에요. 내 도메인을 쓴다면 프로젝트 이름을 바꾸세요.

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

### 로그인

내 도메인을 열고 -e로 입력한 관리자 이메일로 로그인하세요. 생성된 비밀번호는 바로 바꾸세요.

### 컨테이너 확인하기

빠른 시작 가이드에서는 nginx, platform-blue, rag-pipeline-blue, postgres, redis, autoheal, snoopy가 보일 것으로 예상해요.

```
docker ps
```

## CLI로 관리하기

CLI에는 플랫폼 API용 명령도 있어요. 각 작업을 하려면 계정에 해당 권한이 있어야 해요.

-   작업을 실행하기 전에 명령 도움말에서 최신 플래그를 확인하세요.
-   login 명령은 API 기본 URL, 이메일, 비밀번호를 받아요. 돌려받은 세션 토큰을 저장해요.
-   현재 로그인 명령은 성공 로그에 세션 토큰을 그대로 출력해요. 이 출력은 다른 사람에게 보이지 않게 해 주세요.

명령 그룹: `accounts`, `posts`, `apps`, `emojis`, `feeds`, `reports`, `rules`, `settings`.

### 사용할 수 있는 명령 보기

```
./wlycli --help
```

### 배포 명령 보기

```
./wlycli deployment --help
```

### 로그인 옵션 보기

```
./wlycli login --help
```

### 설정 옵션 보기

```
./wlycli settings --help
```

## 업데이트와 복구

기본적으로 배포는 매일 안정 버전 업데이트가 있는지 확인해요. 서버 관리자는 관리 화면에서 릴리스를 관리할 수 있어요.

-   배포 파일은 그대로 쓸 수 있는데 일부 컨테이너가 실패하면, 퀵스타트에서는 restart를 실행하라고 안내해요. restart는 컨테이너를 다시 만들어요.
-   프로젝트 디렉터리나 컨테이너가 아직 남아 있으면 create는 다시 실행되지 않아요.
-   강제 삭제 옵션은 배포 파일과, 함께 설치된 데이터베이스를 모두 삭제해요. 복구 단계가 아니고, 데이터도 보존되지 않아요.
-   deploy-server 스킬은 아직 deployment update라는 이름을 써요. 현재 CLI에는 대신 deployment auto-update가 있어요. 직접 유지 관리를 하기 전에 현재 CLI 도움말을 확인해 주세요.

### 기존 배포에서 컨테이너 다시 만들기

```
./wlycli deploy restart -d example.com
```

저장된 설정으로 컨테이너를 다시 만들어요. 배포 데이터는 삭제하지 않아요.

## AI 어시스턴트로 배포하기

AI 어시스턴트가 SKILL.md 패키지를 지원한다면 공식 deploy-server 스킬을 내려받으세요. DigitalOcean 배포를 안내해 줘요.

지금은 이 스킬이 DigitalOcean만 다뤄요. CLI 퀵스타트는 다른 클라우드와 직접 운영하는 Linux 호스트에서도 쓸 수 있어요.

### 사용 방법

-   패키지 압축을 풀고, 어시스턴트가 스킬을 설치하는 방식대로 deploy-server 디렉터리를 불러오세요.
-   어시스턴트에게 $deploy-server를 사용하라고 요청하세요.
-   스킬이 도메인, DNS 접근 권한, SSH 설정, SMTP 정보, 관리자 이메일을 물어봐요.
-   DigitalOcean VM을 설정할 수 있고, 원하면 관리형 PostgreSQL 데이터베이스도 설정할 수 있어요. 배포 입력값과 관리형 데이터베이스 가격은 함께 확인해요.

### 다운로드하기 전에

-   이 패키지는 원본 스킬을 그대로 복사한 거예요.
-   다운로드와 업데이트 예시가 최신이 아니에요. 현재 안정 버전 다운로드 URL은 이 웹사이트의 퀵스타트에서 확인하세요. 유지 관리 전에 CLI 도움말을 확인해 주세요.
-   이 스킬에는 클라우드 자격 증명이나 실행 중인 서버가 포함되어 있지 않아요. 모든 어시스턴트에서 작동한다고 보장할 수도 없어요.

패키지에 들어 있는 파일: `SKILL.md`, `agents/openai.yaml` 및 `references/digitalocean.md`. 두 다운로드 모두 파일이 같아요.

[deploy-server.zip 다운로드 (10.7 KB)](https://welley.com/downloads/deploy-server.zip) [deploy-server.skill 다운로드 (10.7 KB)](https://welley.com/downloads/deploy-server.skill)

## 참고 문서

전체 CLI 문서와 배포 스킬 파일이에요. 계정 없이 여기서 읽을 수 있어요.

-   [**Welley CLI** docs/index.md](https://welley.com/ko/administrators/docs/cli/)
-   [**빠른 시작: 최소 Welley 배포** docs/quick-start.md](https://welley.com/ko/administrators/docs/quick-start/)
-   [**서버 배포** 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/)