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와 운영체제는 따로)
  • 소스 빌드나 앱 백엔드를 쓰면 컨테이너 레지스트리와 실행기의 자리도 더해요 → 소스 빌드와 앱 백엔드

설치

  1. 설치 폴더를 만들어요. deploy/instance/application.env와, DB·Django·암호화 비밀값이 든 deploy/instance/secrets를 만들어요. 이미 있는 폴더는 덮어쓰지 않고, 비밀값은 찍지 않아요.

    bash
    python3 deploy/configure.py \
      --hostname apps.example.com \
      --s3-bucket company-ai-files \
      --s3-endpoint https://storage.example.com   # AWS S3면 빼요
    
  2. 비밀 관리 도구로 s3_access_key, s3_secret_key를 채워요. S3 자격에는 그 버킷·접두어의 ListBucket, GetObject, PutObject, DeleteObject가 필요하고, 준비 확인이 HeadBucket을 불러요.

  3. 빌드하고, DB를 띄우고, 확인하고, 마이그레이션하고, 첫 회사와 운영자를 만들고, 웹과 워커를 띄워요.

    bash
    docker 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
    
  4. 찍힌 /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 망에서 돌아요.

bash
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-USER iptables 규칙으로 따로 막아요. 실행 환경 점검이 경고로 알려 줘요.
  • 예약 백업(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시간, 한 번)를 찍어요.

    bash
    docker compose -f deploy/compose.production.yaml exec web mothership-recover operator@example.com
    

이어서

  • 운영: 환경 변수, 백업과 복구, 업그레이드, 상태 확인
  • 쓰는 법: 회사 열기와 회사 관리
Esc