Self-hosting

Run SuperFiles on your own infrastructure with Docker.

Self-hosting

SuperFiles runs as a single Docker container with no external runtime dependencies. SQLite is used for metadata; blobs are stored on a mounted volume.

Requirements

Docker 24+ or Docker Compose 2.20+
A Linux host (or any Docker-capable machine)
At least 1 GB RAM and 10 GB free disk space (for blobs)

Quick start with Docker Compose

Create a docker-compose.yml:

services:
  superfiles:
    image: ghcr.io/superfiles/superfiles:latest
    restart: unless-stopped
    ports:
      - "3100:3100"
    environment:
      DATABASE_URL: "/data/superfiles.db"
      BLOB_STORE_PATH: "/data/blobs"
      JWT_SECRET: "change-me-to-a-random-32-char-string"
      APP_URL: "https://files.example.com"
      CDN_BASE_URL: "https://cdn.example.com"
    volumes:
      - superfiles_data:/data

volumes:
  superfiles_data:

Start it:

docker compose up -d

The API is now running on port 3100.

Environment variables

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	Path to the SQLite database file
`BLOB_STORE_PATH`	Yes	—	Directory for content-addressed blob storage
`JWT_SECRET`	Yes	—	Secret for signing session JWTs (min 32 chars)
`APP_URL`	Yes	—	Public URL of the SuperFiles API
`CDN_BASE_URL`	No	`APP_URL`	Public URL prefix for CDN transform URLs
`PORT`	No	`3100`	Port to listen on
`LOG_LEVEL`	No	`info`	`debug` \| `info` \| `warn` \| `error`
`MAX_UPLOAD_SIZE_MB`	No	`100`	Maximum upload size in megabytes

Reverse proxy with Caddy

Put SuperFiles behind Caddy for automatic TLS:

files.example.com {
  reverse_proxy localhost:3100
}

Reverse proxy with nginx

server {
  listen 443 ssl;
  server_name files.example.com;

  # TLS config here (Certbot, etc.)

  location / {
    proxy_pass http://localhost:3100;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_request_buffering off;   # required for streaming PUT uploads
    client_max_body_size 0;        # no limit; SuperFiles enforces MAX_UPLOAD_SIZE_MB
  }
}

Initial setup

On first run, SuperFiles creates the SQLite schema automatically. You’ll need to create the first admin user via the API:

curl -X POST http://localhost:3100/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "changeme",
    "name": "Admin"
  }'

Then sign in and create an API key from the dashboard at http://localhost:3100.

Upgrading

docker compose pull
docker compose up -d

SuperFiles applies schema migrations on startup. Always back up DATABASE_URL and BLOB_STORE_PATH before upgrading.

Backup

Back up both the database and the blob store:

# SQLite snapshot (safe while the API is running)
sqlite3 /path/to/superfiles.db ".backup /path/to/superfiles.db.bak"

# Blob store (rsync-friendly; blobs are immutable once written)
rsync -a /path/to/blobs/ backup-host:/backups/superfiles-blobs/