Docker Deployment

Deploy HugBucket using Docker

HugBucket is distributed as a Docker image at ghcr.io/sachnun/hugbucket. It runs in either S3 or FTP mode depending on the MODE environment variable.

MODE is required. The container exits immediately if it is not set.

Prerequisites

• Docker installed
• A Hugging Face token (HF_TOKEN) with read/write access to your storage buckets

Running HugBucket

S3 mode

The S3 gateway listens on port 9000 and exposes an S3-compatible API.

1. Pull and run the container

   docker run -d \
     -p 9000:9000 \
     -e MODE=s3 \
     -e HF_TOKEN=hf_xxxxx \
     -e AWS_ACCESS_KEY_ID=hugbucket \
     -e AWS_SECRET_ACCESS_KEY=hugbucket \
     ghcr.io/sachnun/hugbucket
   
2. Verify the gateway is running

   Use the AWS CLI to list buckets through the local endpoint:

   aws --endpoint-url http://localhost:9000 s3 ls
   
3. Upload a file

   aws --endpoint-url http://localhost:9000 s3 cp file.txt s3://my-bucket/file.txt
   

If AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are both left empty, S3 authentication is disabled and any client can connect without credentials. Set both to non-empty values to require authentication.

FTP mode

The FTP gateway listens on port 2121 for the control connection and uses ports 30000–30099 for passive data transfers. Path mapping follows /<bucket>/<key>.

1. Pull and run the container

   docker run -d \
     -p 2121:2121 \
     -p 30000-30099:30000-30099 \
     -e MODE=ftp \
     -e HF_TOKEN=hf_xxxxx \
     -e FTP_USERNAME=hugbucket \
     -e FTP_PASSWORD=hugbucket \
     ghcr.io/sachnun/hugbucket
   
2. Connect with an FTP client

   ftp localhost 2121
   # username: hugbucket
   # password: hugbucket
   

You must publish the full passive port range (30000-30099) alongside the control port (2121). Without it, passive mode transfers will fail to establish a data connection.

To enable anonymous access, omit both FTP_USERNAME and FTP_PASSWORD. Setting only one of the two is a configuration error and will cause the server to refuse to start.

Port reference

Port	Protocol	Description
9000	TCP	S3 API endpoint
2121	TCP	FTP control connection
30000–30099	TCP	FTP passive data connections

These are the ports declared with EXPOSE in the Dockerfile. Publish only the ports relevant to your chosen mode.

Docker Compose

The following Compose file shows both modes as separate services. Run only the service for the mode you need.

docker-compose.yml

services:
  hugbucket-s3:
    image: ghcr.io/sachnun/hugbucket
    ports:
      - "9000:9000"
    environment:
      MODE: s3
      HF_TOKEN: hf_xxxxx
      AWS_ACCESS_KEY_ID: hugbucket
      AWS_SECRET_ACCESS_KEY: hugbucket
    restart: unless-stopped

  hugbucket-ftp:
    image: ghcr.io/sachnun/hugbucket
    ports:
      - "2121:2121"
      - "30000-30099:30000-30099"
    environment:
      MODE: ftp
      HF_TOKEN: hf_xxxxx
      FTP_USERNAME: hugbucket
      FTP_PASSWORD: hugbucket
    restart: unless-stopped

Start a single service:

# S3 only
docker compose up -d hugbucket-s3

# FTP only
docker compose up -d hugbucket-ftp

Do not run both services simultaneously with the same HF_TOKEN if they target the same Hugging Face namespace, unless you have tested for write conflicts.