Mothership
운영 설치
PostgreSQL, S3 호환 버킷, 웹과 워커를 나눈 운영 Compose로 Mothership을 설치하고, 첫 운영자로 로그인해요.
운영의 기준은 deploy/compose.production.yaml이에요: PostgreSQL, 기존 S3 호환 버킷, 따로 도는 웹과 워커, 앞의 HTTPS 리버스 프록시. 루트의 compose.yaml과 fly.toml은 개발·미리보기용이에요.
필요한 것
- Docker Engine과 Compose v2 이상
- HTTPS 호스트 이름과 리버스 프록시
- S3 호환 버킷(AWS S3, MinIO, R2 등). 이 설치만의 접두어(prefix)와 버전 관리를 권해요
- 앱과 워커에 4 GiB 이상의 메모리(DB와 운영체제는 따로)
- 소스 빌드나 앱 백엔드를 쓰면 컨테이너 레지스트리와 실행기의 자리도 더해요 → 소스 빌드와 앱 백엔드
설치
-
설치 폴더를 만들어요.
deploy/instance/application.env와, DB·Django·암호화 비밀값이 든deploy/instance/secrets를 만들어요. 이미 있는 폴더는 덮어쓰지 않고, 비밀값은 찍지 않아요.bashpython3 deploy/configure.py \ --hostname apps.example.com \ --s3-bucket company-ai-files \ --s3-endpoint https://storage.example.com # AWS S3면 빼요 -
비밀 관리 도구로
s3_access_key,s3_secret_key를 채워요. S3 자격에는 그 버킷·접두어의 ListBucket, GetObject, PutObject, DeleteObject가 필요하고, 준비 확인이 HeadBucket을 불러요. -
빌드하고, DB를 띄우고, 확인하고, 마이그레이션하고, 첫 회사와 운영자를 만들고, 웹과 워커를 띄워요.
bashdocker compose -f deploy/compose.production.yaml build docker compose -f deploy/compose.production.yaml up -d db docker compose -f deploy/compose.production.yaml run --rm tools manage check_deployment --production docker compose -f deploy/compose.production.yaml run --rm migrate docker compose -f deploy/compose.production.yaml run --rm tools manage bootstrap_installation \ --organization acme --name 'Acme Corporation' --email operator@example.com docker compose -f deploy/compose.production.yaml up -d web workers -
찍힌
/login주소를 열고operator@example.com으로 코드를 받아 로그인해요.SMTP_URL이 없으면 코드는 웹 서버 로그에 있어요.
- 새 설치는 PostgreSQL 18(
postgres:18-trixie)로 시작해요.configure.py가deploy/.env에 그 두 줄을 고정해요. 지우면 예전 설치처럼 17로 떠요. - 초기화는 몇 번 해도 같아요. 기존 자격을 초기화하거나 다른 계정을 올리지 않아요. 비밀번호 옵션과
bootstrap_password파일은 더 이상 쓰지 않아요.
소스 빌드와 앱 백엔드
이미 빌드한 프런트엔드 ZIP을 올리는 것만으로 쓰면 위의 web과 workers로 충분해요. 아래 둘 가운데 하나라도 하려면 소스 빌드 실행기(delivery, manage application_worker)를 따로 띄워요.
- 갈피 프로젝트를 이어 앱을 개발할 때. 갈피는 소스 ZIP만 보내고 빌드는 Mothership이 해요. 실행기가 없으면 빌드 요청이 처리되지 않고 기다려요.
- 앱에 Python·Node 백엔드가 있을 때. 실행기가 백엔드 컨테이너를 만들고 띄워요.
| 필요한 것 | 메모 |
|---|---|
| 빌드 도구 이미지 | deploy/application/toolchain.Dockerfile로 만들어 레지스트리에 올리고, MOTHERSHIP_BUILD_IMAGE에 digest로 고정해요(이름@sha256:… 꼴만 받아요) |
| 실행 환경 | Docker socket 또는 Kubernetes. 서비스 관리 → 실행 환경에서 더하고 점검하고 기본으로 정해요 |
| Kubernetes일 때 | 원격 BuildKit(MOTHERSHIP_BUILDX_BUILDER)과 앱 이미지 저장소(MOTHERSHIP_IMAGE_REPOSITORY). 지금은 Mothership과 같은 클러스터만 돼요 |
Docker socket으로 띄우는 법이에요. socket은 실행기에만 마운트하고, 앱 컨테이너는 따로 된 mothership-apps 망에서 돌아요.
export MOTHERSHIP_BUILD_IMAGE=registry.example/toolchain@sha256:…
export MOTHERSHIP_DOCKER_GID=$(stat -c %g /var/run/docker.sock)
docker compose -f deploy/compose.production.yaml -f deploy/application/compose.docker.yaml up -d --build
- Docker API로는 앱 망에서 사설 대역과 호스트로 나가는 연결을 막을 수 없어요. 호스트의
DOCKER-USERiptables 규칙으로 따로 막아요. 실행 환경 점검이 경고로 알려 줘요. - 예약 백업(
deploy/operations.py)을 쓰면 두 값을export대신deploy/.env에 적고,operations.json의writer_services에delivery를 더해요. - 자세한 설정과 Kubernetes 예시는 저장소의
deploy/managed-compute.md에 있어요.
리버스 프록시
- 웹은
127.0.0.1:8080에 묶여 있어요. 믿는 리버스 프록시에서 TLS를 끝내고Host를 공개 호스트 이름으로,X-Forwarded-Proto: https를 넣어요. - 클라이언트가 보낸 전달 헤더는 지우고 자기 것을 넣어요. 로그인 제한이 믿을 프록시는
MOTHERSHIP_TRUSTED_PROXIES예요. - SSE에는 버퍼링을 끄고, 스트림 기한만큼 긴 요청을 허용하고, 업로드 한도를 플랫폼 파일 한도보다 크게 둬요.
운영자
-
ADMIN_EMAILS(쉼표로 여러 개)의 사람은 시작할 때마다 운영자가 돼요(manage ensure_operators). 목록에서 빼기 전에 강등하면 다음 시작에 다시 운영자가 돼요. -
메일이나 SSO를 잃었을 때 복구 링크(1시간, 한 번)를 찍어요.
bashdocker compose -f deploy/compose.production.yaml exec web mothership-recover operator@example.com
이어서
설치 방법 · 배포