Docker로 배포

Hollo는 GitHub Packages에서 공식 Docker 이미지를 제공합니다. 그 이미지를 여러분의 로컬 머신에서 Hollo를 배포할 수 있습니다:

docker pull ghcr.io/fedify-dev/hollo:latest

Hollo를 돌리려면, PostgreSQL 데이터베이스와 미디어 저장을 위한 S3 호환 오브젝트 스토리지가 필요합니다. PostgreSQL 공식 Docker 이미지와 S3 호환 오브젝트 스토리지인 RustFS를 쓸 수 있습니다. 아니면 AWS RDS, ElastiCache, S3와 같은 관리형 서비스를 사용할 수도 있습니다.

Hollo에 해당 서비스들을 연결하려면, docker run 명령의 -e/--env 옵션이나 --env-file 옵션을 통해 환경 변수를 설정해야 합니다. Hollo가 지원하는 환경 변수 목록은 환경 변수 챕터에서 확인할 수 있습니다.

Docker Compose

PostgreSQL과 S3 호환 오브젝트 스토리지 등과 Hollo를 묶어서 배포하기 위해, Docker Compose를 사용할 수도 있습니다. 아래는 compose.yaml 파일의 예시입니다:

# If you are upgrading from the former MinIO-based Compose setup, migrate your
# media before starting this file.  See the Docker installation guide:
# https://docs.hollo.social/install/docker/#migrating-from-minio

services:
  hollo:
    image: ghcr.io/fedify-dev/hollo:canary
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: "postgres://user:password@postgres:5432/database"
      SECRET_KEY: "${SECRET_KEY}"
      LOG_LEVEL: "${LOG_LEVEL}"
      BEHIND_PROXY: "${BEHIND_PROXY}"
      DRIVE_DISK: s3
      STORAGE_URL_BASE: http://localhost:9000/hollo/
      S3_REGION: us-east-1
      S3_BUCKET: hollo
      S3_ENDPOINT_URL: http://rustfs:9000
      S3_FORCE_PATH_STYLE: "true"
      AWS_ACCESS_KEY_ID: rustfsadmin
      AWS_SECRET_ACCESS_KEY: rustfsadmin
      # MEDIA_PROXY: off                # or "proxy" / "cache" — see docs/install/env
      # REMOTE_MEDIA_THUMBNAILS: "on"   # set to "off" to skip local thumbnails
    depends_on:
      postgres:
        condition: service_started
      rustfs:
        condition: service_healthy
      create-bucket:
        condition: service_completed_successfully
    restart: unless-stopped

  postgres:
    image: postgres:17
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: database
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  rustfs:
    image: rustfs/rustfs:1.0.0-beta.8
    ports:
      - "9000:9000"
    environment:
      RUSTFS_ACCESS_KEY: rustfsadmin
      RUSTFS_SECRET_KEY: rustfsadmin
    volumes:
      - rustfs_data:/data
    command: ["/data"]
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:9000/health"]
      interval: 2s
      timeout: 2s
      retries: 30
    restart: unless-stopped

  create-bucket:
    image: public.ecr.aws/aws-cli/aws-cli:2.35.21
    depends_on:
      rustfs:
        condition: service_healthy
    environment:
      AWS_ACCESS_KEY_ID: rustfsadmin
      AWS_SECRET_ACCESS_KEY: rustfsadmin
      AWS_DEFAULT_REGION: us-east-1
      AWS_ENDPOINT_URL: http://rustfs:9000
      BUCKET_POLICY: >-
        {"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":"*","Action":["s3:GetObject"],"Resource":["arn:aws:s3:::hollo/*"]}]}
    entrypoint: ["/bin/sh", "-c"]
    command:
      - |
        until aws s3api head-bucket --bucket hollo 2>/dev/null; do
          aws s3api create-bucket --bucket hollo && break
          sleep 1
        done
        aws s3api put-bucket-policy \
          --bucket hollo \
          --policy "$${BUCKET_POLICY}"

volumes:
  postgres_data:
  rustfs_data:

위 파일을 작업 디렉터리에 compose.yaml로 저장한 다음, 다음 명령을 실행하면 됩니다:

docker compose up -d

MinIO에서 마이그레이션

Hollo 0.10.0 이전의 Compose 파일은 미디어를 MinIO 볼륨에 저장했습니다. RustFS는 이 볼륨을 직접 사용할 수 없으므로, 새로운 Compose 구성을 시작하기 전에 S3 API를 통해 객체를 복사해야 합니다.

[!CAUTION] 기존 설치와 같은 디렉터리에서 같은 Compose 프로젝트 이름을 사용해 다음 명령을 실행하세요. 미디어가 든 볼륨을 삭제하므로 docker compose down -v는 실행하지 마세요.

현재 Compose 파일을 백업하고 볼륨을 남겨 둔 채 기존 서비스를 중지합니다. 그런 다음 새 Compose 파일과 마이그레이션 오버레이를 다운로드하세요:

cp compose.yaml compose.minio.yaml
docker compose down
curl -LO https://raw.githubusercontent.com/fedify-dev/hollo/main/compose.yaml
curl -LO https://raw.githubusercontent.com/fedify-dev/hollo/main/compose.migrate-minio.yaml

compose.yaml을 직접 수정해 사용했다면 계속하기 전에 compose.minio.yaml에서 해당 변경을 다시 적용하세요. 새 RustFS 서비스와 스토리지 설정은 유지해야 합니다.

이전에 COMPOSE_PROJECT_NAME이나 docker compose -p를 사용했다면 아래의 모든 명령에도 같은 값을 사용하세요. hollo 버킷을 RustFS로 복사한 뒤 원본과 대상이 일치하는지 검사합니다:

docker compose -f compose.yaml -f compose.migrate-minio.yaml \
  --profile migrate-minio run --rm migrate-minio
docker compose -f compose.yaml -f compose.migrate-minio.yaml \
  --profile migrate-minio run --rm verify-minio-migration

검사 명령은 차이가 없다고 보고해야 합니다. 볼륨을 삭제하지 않고 임시 마이그레이션 서비스를 중지한 다음 Hollo를 평소처럼 시작하세요:

docker compose -f compose.yaml -f compose.migrate-minio.yaml \
  --profile migrate-minio down
docker compose up -d

기존 미디어 URL 여러 개가 정상적으로 열리는지 확인한 뒤에도, 마이그레이션된 데이터를 별도로 백업할 때까지 기존 minio_data 볼륨을 보관하세요.