helix-db Docker & Self-Hosted Deployment

services:
  seaweedfs:
    image: ghcr.io/chrislusf/seaweedfs:4.47@sha256:ce9e796f1fe6f06968f4c04bdaf8f678dad9c8acdfef3d244133d71bfa6bf882
    platform: ${HELIX_IMAGE_PLATFORM:?HELIX_IMAGE_PLATFORM must be set}
    command:
      - mini
      - -dir=/data
      - -bucket=helix-db
      - -s3.config=/etc/seaweedfs/s3.json
      - -master.telemetry=false
      - -admin.ui=false
      - -webdav=false
      - -s3.port.iceberg=0
      - -s3.port.lance=0
    restart: unless-stopped
    configs:
      - source: seaweedfs-s3
        target: /etc/seaweedfs/s3.json
    volumes:
      - seaweedfs-data:/data
    healthcheck:
      # A signed HEAD proves the S3 gateway, the static identity, and the
      # startup-created bucket are all ready before Helix opens its store.
      test:
        - CMD
        - curl
        - -fsS
        - -o
        - /dev/null
        - --max-time
        - "2"
        - -I
        - --aws-sigv4
        - aws:amz:us-east-1:s3
        - --user
        - helix:helix-local-secret
        - http://127.0.0.1:8333/helix-db
      interval: 1s
      timeout: 5s
      retries: 120

  # Test-only request logger. Helix reaches SeaweedFS through it so the idle
  # refresh regression can observe every object GET and its Range header.
  s3-trace:
    image: ghcr.io/nginx/nginx-unprivileged:1.30.5-alpine@sha256:4714e0b1b2577eaa1a6131d07c958b67f0eb68e6d0521e90c6e5287db8cf0bc5
    platform: ${HELIX_IMAGE_PLATFORM:?HELIX_IMAGE_PLATFORM must be set}
    restart: unless-stopped
    depends_on:
      seaweedfs:
        condition: service_healthy
    volumes:
      - ./s3-trace.conf:/etc/nginx/conf.d/default.conf:ro

  helix:
    image: ${HELIX_IMAGE_REF:?HELIX_IMAGE_REF must be set}
    platform: ${HELIX_IMAGE_PLATFORM:?HELIX_IMAGE_PLATFORM must be set}
    pull_policy: never
    restart: unless-stopped
    depends_on:
      seaweedfs:
        condition: service_healthy
      s3-trace:
        condition: service_started
    ports:
      - "${HELIX_IMAGE_TEST_PORT:-18120}:8080"
    # S3 storage always caches on local disk, in /var/cache/helix unless
    # HELIX_DISK_CACHE_DIR moves it. On tmpfs every container start begins
    # cold, so reopened reads must come from SeaweedFS and reach the trace.
    # Reads repeated after that are served from the cache and never traced,
    # so the idle refresh check proves only that idle refreshes fetch no
    # uncached SST ranges. A tmpfs root is root-owned 0755 unless its mode
    # lets the 65532 runtime user write, and the explicit budget stays within
    # its size, where the 8 GiB default would not fit and fail startup.
    tmpfs:
      - /var/cache/helix:mode=1777,size=2g
    environment:
      HELIX_DISK_CACHE_BYTES: "1073741824"
      S3_BUCKET: helix-db
      S3_REGION: us-east-1
      DB_PATH: db/
      AWS_ACCESS_KEY_ID: helix
      AWS_SECRET_ACCESS_KEY: helix-local-secret
      AWS_ENDPOINT: http://s3-trace:8333
      AWS_ALLOW_HTTP: "true"

configs:
  seaweedfs-s3:
    content: |
      {
        "identities": [
          {
            "name": "helix",
            "credentials": [
              {"accessKey": "helix", "secretKey": "helix-local-secret"}
            ],
            "actions": ["Read:helix-db", "Write:helix-db", "List:helix-db"]
          }
        ]
      }

volumes:
  seaweedfs-data: