paste.es/docs/docker.md

Docker Deployment

Complete guide for deploying Hemmelig using Docker.

Architecture Support

Hemmelig Docker images are built for multiple architectures:

Architecture	Supported	Use Case
linux/amd64	Yes	Intel/AMD servers, most cloud providers
linux/arm64	Yes	Apple Silicon, AWS Graviton, Raspberry Pi 4+

Docker will automatically pull the correct image for your platform.

Quick Start

docker run -d \
  --name hemmelig \
  -p 3000:3000 \
  -v hemmelig-data:/app/database \
  -v hemmelig-uploads:/app/uploads \
  -e DATABASE_URL="file:/app/database/hemmelig.db" \
  -e BETTER_AUTH_SECRET="your-secret-key-min-32-chars" \
  -e BETTER_AUTH_URL="https://your-domain.com" \
  hemmeligapp/hemmelig:v7

Docker Compose

The repository includes a ready-to-use docker-compose.yml:

# Clone the repository
git clone https://github.com/HemmeligOrg/Hemmelig.app.git
cd Hemmelig.app

# Edit environment variables
nano docker-compose.yml

# Start the application
docker compose up -d

Configuration

The included docker-compose.yml uses SQLite:

services:
    hemmelig:
        image: hemmeligapp/hemmelig:v7
        container_name: hemmelig
        restart: unless-stopped
        volumes:
            - ./database:/app/database
            - ./uploads:/app/uploads
        environment:
            - DATABASE_URL=file:/app/database/hemmelig.db
            - BETTER_AUTH_SECRET=change-this-to-a-secure-secret-min-32-chars
            - BETTER_AUTH_URL=https://secrets.example.com
            - NODE_ENV=production
            - HEMMELIG_BASE_URL=https://secrets.example.com
        ports:
            - '3000:3000'
        healthcheck:
            test:
                [
                    'CMD',
                    'wget',
                    '--no-verbose',
                    '--tries=1',
                    '--spider',
                    'http://localhost:3000/api/health/ready',
                ]
            interval: 30s
            timeout: 10s
            retries: 3
            start_period: 10s

Important: Before starting, update the following:

• BETTER_AUTH_SECRET - Generate with openssl rand -base64 32
• HEMMELIG_BASE_URL - Your public domain URL

Volume Mounts

Container Path	Purpose	Required
/app/database	SQLite database storage	Yes
/app/uploads	File upload storage	Yes

Environment Variables

See Environment Variables for a complete reference.

Required Variables

Variable	Description
DATABASE_URL	Database connection string
BETTER_AUTH_SECRET	Authentication secret (min 32 characters)
BETTER_AUTH_URL	Public URL of your instance (for proper cookie handling)

Common Variables

Variable	Description	Default
NODE_ENV	Set to production for production deployments	development
HEMMELIG_BASE_URL	Public URL of your instance	-
HEMMELIG_PORT	Internal port (usually leave as default)	3000

Troubleshooting

Database Permission Errors

If you see errors like:

Error: Migration engine error:
SQLite database error
unable to open database file: /app/database/hemmelig.db

This means the container cannot write to the mounted volume. Fix by setting correct ownership on the host:

# Find your user ID
id -u

# Create directories and set ownership
sudo mkdir -p ./database ./uploads
sudo chown -R $(id -u):$(id -g) ./database ./uploads

Or use Docker named volumes instead of bind mounts:

volumes:
    - hemmelig-data:/app/database
    - hemmelig-uploads:/app/uploads

File Upload Permission Errors

If file uploads fail, ensure the uploads directory has correct permissions:

sudo chown -R $(id -u):$(id -g) ./uploads
chmod 755 ./uploads

Container User

The Hemmelig container runs as user bun (non-root) for security. When using bind mounts, ensure the host directories are writable by UID 1000 (the default bun user in the container).

Building from Source

To build the Docker image locally:

git clone https://github.com/HemmeligOrg/Hemmelig.app.git
cd Hemmelig.app
docker build -t hemmelig .

Building for ARM64

To build for ARM64 (e.g., for Apple Silicon or AWS Graviton):

# Set up Docker buildx with multi-architecture support
docker buildx create --name multiarch --driver docker-container --use

# Build for ARM64
docker buildx build --platform linux/arm64 -t hemmelig:arm64 --load .

# Build for both architectures
docker buildx build --platform linux/amd64,linux/arm64 -t hemmelig:latest --push .

The Dockerfile uses a cross-compilation strategy where Prisma client generation runs on the build host's native architecture to avoid QEMU emulation issues.

Reverse Proxy

Nginx

1. Create the Nginx configuration file:

sudo nano /etc/nginx/sites-available/hemmelig

2. Add the following configuration (HTTP only, for initial setup):

server {
    listen 80;
    server_name your_domain.com; # Replace with your domain or IP

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_cache_bypass $http_upgrade;
    }
}

3. Enable the site:

sudo ln -s /etc/nginx/sites-available/hemmelig /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4. Install Certbot and obtain SSL certificate:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your_domain.com

Certbot will automatically modify your Nginx configuration to use HTTPS.

## Health Checks

The container exposes a health endpoint at `/api/health/ready`. The built-in healthcheck uses `wget` to verify the application is responding and all dependencies (database, storage) are healthy.

To manually check:

```bash
curl http://localhost:3000/api/health/ready
# Returns: JSON with status and component health details

Updating

# Pull latest image
docker pull hemmeligapp/hemmelig:v7

# Recreate container
docker compose down
docker compose up -d

Database migrations run automatically on startup.

Security Notes

1. Always use HTTPS in production with a reverse proxy
2. Generate secure secrets: openssl rand -base64 32
3. Keep the image updated for security patches
4. Back up your data regularly, especially the database