Deploy using Docker

Hollo provides the official Docker images on GitHub Packages. You can use them to deploy Hollo on your server or your local machine:

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

To run Hollo, you need to set up a PostgreSQL database and an S3-compatible object storage for media storage. You can use the official Docker image for PostgreSQL, and you can use RustFS for the S3-compatible object storage. Or you can use other managed services like AWS RDS, ElastiCache, and S3.

To connect Hollo to these services, you need to set the environment variables through docker run command’s -e/--env option or --env-file option. To list the environment variables that Hollo supports, see the Environment variables chapter.

Docker Compose

To wire up these services, you can use Docker Compose. Here’s an example compose.yaml file:

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:

Save this file as compose.yaml in your working directory, and then run the following command:

docker compose up -d

Migrating from MinIO

Compose files published before Hollo 0.10.0 stored media in a MinIO volume. RustFS cannot use that volume directly. Copy its objects through the S3 API before starting the new Compose setup.

[!CAUTION] Run these commands from the same directory and with the same Compose project name as your existing installation. Do not use docker compose down -v, because it deletes the volume that contains your media.

Back up the current Compose file and stop the old services without deleting their volumes. Then download the new Compose file and the migration overlay:

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

If you customized compose.yaml, reapply those changes from compose.minio.yaml before continuing. Keep the new RustFS service and storage settings.

If you previously set COMPOSE_PROJECT_NAME or used docker compose -p, use the same value for every command below. Copy the hollo bucket to RustFS, then compare the source and destination:

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

The verification command must report no differences. Stop the temporary migration services without deleting their volumes, then start Hollo normally:

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

Check several existing media URLs before removing the old minio_data volume. Keep that volume until you have also backed up the migrated data.