All-in-One Setup (Recommended)

The easiest way to self-host heaper. A single Docker image bundles the heaper server, sync layer, and PostgreSQL — no external dependencies needed.

Docker Compose

Create a docker-compose.yml

services:
  heaper:
    image: ghcr.io/janlunge/heaper:latest
    platform: linux/amd64   # Required on ARM (Raspberry Pi, Apple Silicon)
    container_name: heaper
    restart: unless-stopped
    mem_limit: 4g
    memswap_limit: 4g
    ports:
      - "3010:80"
      # - "5432:5432"  # Uncomment to expose PostgreSQL externally
    environment:
      - HOSTNAME=localhost
      - POSTGRES_USER=heaper
      - POSTGRES_PASSWORD=change-me-please
      - POSTGRES_DB=heaper
      - ENABLE_INTERNAL_POSTGRES=true
    volumes:
      - ./heaper-data/postgres:/var/lib/postgresql/data
      - ./heaper-data/data:/usr/src/app/data
      - ./heaper-data/config:/usr/src/app/config
      - ./heaper-data/thumbnails:/mnt/thumbnails
      - ./heaper-data/storage:/mnt/storage
      - ./heaper-data/backups:/mnt/backups

Before first run: Change POSTGRES_PASSWORD to a secure password.

Start it:

docker-compose up -d

Access: http://localhost:3010

Docker Run

Same image, without compose:

docker run -d --name heaper-selfhost --platform linux/amd64 \
  -p 3010:80 \
  -e HOSTNAME=your-domain.com \
  -e POSTGRES_PASSWORD=your-secure-password \
  --volume /path/to/heaper/postgres:/var/lib/postgresql/data \
  --volume /path/to/heaper/config:/usr/src/app/config \
  --volume /path/to/heaper/data:/usr/src/app/data \
  --volume /path/to/heaper/thumbnails:/mnt/thumbnails \
  --volume /path/to/heaper/storage:/mnt/storage \
  --volume /path/to/heaper/backups:/mnt/backups \
  ghcr.io/janlunge/heaper:latest

Add -p 5432:5432 for external PostgreSQL access.

Environment Variables

Volumes

All data is stored under ./heaper-data/ when using Docker Compose:

Next Steps

• Backup & Restore
• Troubleshooting
• Connecting to your server