Docker Compose로 배포하기

머신 한 대에서 BostonIvy 전체를 실행합니다. PostgreSQL, 서버, BostonIvy Web의 구성은 bostonivy-os 저장소의 deploy/compose.yaml에 정의되어 있습니다. 가장 빨리 시작하는 방법이며, 가족이나 작은 팀이라면 이것으로 충분합니다.

시작하기 전에

Docker와 Compose v2(docker compose version이 v2.x를 출력해야 합니다).
배포 파일: bostonivy-os의 deploy 폴더. compose.yaml, https.yaml, .env.example이 들어 있습니다.
이미지 접근 권한. 이미지는 GitHub Container Registry의 비공개 패키지입니다. read:packages 범위가 있는 GitHub 토큰으로 한 번 로그인합니다.

echo "$GITHUB_TOKEN" | docker login ghcr.io -u <GitHub 사용자 이름> --password-stdin

BostonIvy 시작하기

예제에서 설정 파일을 만듭니다.
```
cd deploy
cp .env.example .env
```
서버 시크릿을 생성하고 .env의 BOSTONIVY_AUTH_SECRET에 붙여 넣습니다.
```
docker compose run --rm --no-deps bostonivy keygen
```
모든 서비스를 시작합니다.
```
docker compose up -d
```
http://localhost:8080 을 열고 계정을 만듭니다. 새 데이터베이스에서는 첫 번째 계정이 관리자가 됩니다. 그 뒤 다른 사람이 가입할 수 있는지는 auth.open_registration과 관리자 패널의 설정에 따라 정해집니다.

docker compose ps에서 세 서비스가 모두 healthy로 보이면 됩니다. 서버는 시작할 때마다 데이터베이스를 마이그레이션하므로 따로 실행할 것은 없습니다.

예제 .env는 BOSTONIVY_COOKIE_SECURE=false로 되어 있으며, 이는 http://localhost에서만 동작합니다. 다른 사람이 사용하기 전에 HTTPS를 설정하고(아래 참고) 값을 true로 바꾸세요.

설정

모든 설정은 deploy/.env에 있습니다.

변수	의미
`BOSTONIVY_AUTH_SECRET`	필수. 모든 서명 키와 암호화 키가 여기서 파생됩니다. 잃어버리면 모두 다시 로그인해야 하고, 암호화해 저장한 TOTP와 webhook 시크릿도 복호화할 수 없습니다. 꼭 백업하세요
`BOSTONIVY_URL`	사용자가 여는 주소. 메일 속 링크와 공유 링크에 쓰입니다
`BOSTONIVY_PORT`	이 머신에서 여는 포트. 기본값은 `8080`
`BOSTONIVY_COOKIE_SECURE`	운영 환경에서는 `true`(HTTPS 필요). `false`는 `http://localhost`에서 체험할 때만 쓰세요. 그렇지 않으면 페이지를 새로 고칠 때 로그인이 풀립니다
`BOSTONIVY_SMTP_URL`, `BOSTONIVY_MAIL_FROM`	메일 설정. 예: `smtps://user:password@smtp.example.com`과 `BostonIvy <noreply@example.com>`. 비워 두면 메일을 보내지 않고, `log`로 두면 메일을 서버 로그에 기록하므로 체험할 때 편리합니다
`POSTGRES_PASSWORD`	데이터베이스 비밀번호
`BOSTONIVY_VERSION`	이미지 태그. `latest`는 최신 릴리스를 따릅니다
`BOSTONIVY_SITE`	Caddy의 사이트 주소. 아래 HTTPS를 참고하세요

그 밖의 서버 설정(요청 제한, Redis, webhook, 오브젝트 스토리지, 계정 삭제 유예 기간 등)은 BOSTONIVY_<섹션>__<키> 형식의 환경 변수로 지정할 수 있습니다. 예: BOSTONIVY_STORAGE__KIND=s3. compose.yaml의 bostonivy.environment 아래에 추가하면 됩니다. 전체 항목은 bostonivy-os의 bostonivy.example.toml에 있습니다.

HTTPS

둘 중 하나를 고르세요.

Caddy가 인증서를 받게 하기. 도메인이 이 머신을 가리키게 한 뒤 .env에 다음을 설정합니다.
```
BOSTONIVY_SITE=tasks.example.com
BOSTONIVY_URL=https://tasks.example.com
BOSTONIVY_COOKIE_SECURE=true
```
그리고 HTTPS용 오버라이드와 함께 시작합니다. 포트 80과 443이 열립니다.
```
docker compose -f compose.yaml -f https.yaml up -d
```
Caddy가 인증서 발급과 갱신을 알아서 하고 caddy 볼륨에 보관합니다.
이미 운영 중인 리버스 프록시 뒤에 두기. BOSTONIVY_SITE=:80을 그대로 두고 프록시가 BOSTONIVY_PORT로 전달하게 합니다. 실시간 업데이트를 전달하는 /api/v1/realtime의 WebSocket 연결도 전달되는지 확인하세요.

백업과 업그레이드

백업할 것은 세 가지입니다.

데이터베이스:

docker compose exec postgres pg_dump -U bostonivy bostonivy > backup.sql

첨부 파일과 아바타: files 볼륨(S3로 옮겼다면 해당 버킷).
시크릿: .env의 BOSTONIVY_AUTH_SECRET.

업그레이드는 새 이미지를 받아 다시 시작하면 됩니다.

docker compose pull && docker compose up -d

새 버전은 시작할 때 데이터베이스를 마이그레이션합니다. 마이그레이션은 추가만 하고 삭제하지 않으므로, 백업과 함께라면 이전 버전으로 되돌릴 수 있습니다.

명령줄

docker compose exec bostonivy bostonivy admin promote <사용자 이름>   # 관리자로 지정
echo "새 비밀번호" | docker compose exec -T bostonivy bostonivy admin set-password <사용자 이름>
docker compose exec bostonivy bostonivy health                       # 상태 확인

이미지 직접 빌드하기

bostonivy-web을 bostonivy-os 옆에 체크아웃하거나 .env의 BOSTONIVY_WEB_SOURCE로 위치를 지정합니다. 웹 앱은 비공개 BostonIvy 디자인 패키지를 사용하므로, 빌드하려면 IvyLabsApp의 비공개 저장소를 읽을 수 있는 토큰이 필요합니다. 토큰은 빌드 시크릿으로만 쓰이고 이미지에는 남지 않습니다.

cd deploy
GITHUB_TOKEN=$(gh auth token) docker compose build
docker compose up -d