Docker Deployment

Deploy TrailBase using Docker and docker-compose with persistent storage and configuration

TrailBase provides official Docker images for easy containerized deployment. The images are multi-arch and support both x86_64 and ARM64 architectures.

Docker Image

The official TrailBase Docker image is available on Docker Hub:

docker pull trailbase/trailbase:latest

Image details:

• Base: Alpine Linux 3.22
• User: Runs as unprivileged trailbase user
• Architectures: linux/amd64, linux/arm64
• Entrypoint: Uses tini for proper signal handling
• Health check: Built-in health check on /api/healthcheck

Quick Start

Run TrailBase in a Docker container with persistent storage:

# Create data directory with proper permissions
mkdir -p traildepot

# Run TrailBase
docker run -d \
  --name trailbase \
  -p 4000:4000 \
  -v "$(pwd)/traildepot:/app/traildepot" \
  -e RUST_BACKTRACE=1 \
  --restart unless-stopped \
  trailbase/trailbase:latest

# Check logs for admin credentials
docker logs trailbase

Docker will create the traildepot directory with root ownership if it doesn’t exist. The TrailBase container runs as an unprivileged user and will encounter permission errors. Always create the directory first with proper permissions.

Docker Compose

The recommended way to run TrailBase with Docker is using docker-compose:

1. Create docker-compose.yml

   Create a docker-compose.yml file based on the official template:

   docker-compose.yml

   services:
     trail:
       image: docker.io/trailbase/trailbase:latest
       ports:
         - "${PORT:-4000}:4000"
       restart: unless-stopped
       volumes:
         # Mount the data directory
         - ${DATA_DIR:-.}/traildepot:/app/traildepot
       environment:
         RUST_BACKTRACE: "1"
       # Optional: override the default command
       # command: "/app/trail --data-dir /app/traildepot run --address 0.0.0.0:4000"
   
2. Create data directory

   Create the data directory with proper permissions:

   mkdir -p traildepot
   chown -R $(id -u):$(id -g) traildepot
   
3. Start the service

   docker-compose up -d
   
4. View logs

   docker-compose logs -f trail
   

   On first start, the logs will contain the admin credentials.

The docker-compose file uses environment variables for easy customization. Set PORT to change the exposed port and DATA_DIR to change the data directory location.

Configuration Options

Environment Variables

Configure TrailBase through environment variables in docker-compose:

docker-compose.yml

services:
  trail:
    image: docker.io/trailbase/trailbase:latest
    ports:
      - "4000:4000"
    environment:
      # Global options
      DATA_DIR: "/app/traildepot"
      PUBLIC_URL: "https://yourdomain.com"
      
      # Server options
      ADDRESS: "0.0.0.0:4000"
      ADMIN_ADDRESS: "0.0.0.0:4001"
      SPA: "true"
      
      # Development
      RUST_BACKTRACE: "1"
      
      # Runtime options
      RUNTIME_THREADS: "4"
    volumes:
      - ./traildepot:/app/traildepot

Custom Command

Override the default command for advanced configuration:

docker-compose.yml

services:
  trail:
    image: docker.io/trailbase/trailbase:latest
    command: >
      /app/trail
        --data-dir /app/traildepot
        --public-url https://yourdomain.com
        run
        --address 0.0.0.0:4000
        --spa
        --public-dir /app/public
    volumes:
      - ./traildepot:/app/traildepot
      - ./public:/app/public:ro

Volume Mounts

Mount additional volumes for static files or WASM components:

docker-compose.yml

services:
  trail:
    image: docker.io/trailbase/trailbase:latest
    volumes:
      # Data directory (required)
      - ./traildepot:/app/traildepot
      
      # Static files for SPA
      - ./dist:/app/public:ro
      
      # Custom WASM components
      - ./wasm:/app/traildepot/wasm:ro
      
      # GeoIP database
      - ./GeoLite2-City.mmdb:/app/geoip.mmdb:ro
    environment:
      PUBLIC_DIR: "/app/public"
      SPA: "true"
      GEOIP_DB_PATH: "/app/geoip.mmdb"

Kubernetes Deployment

For Kubernetes deployments, TrailBase provides example manifests:

1. Create PersistentVolumeClaim

   trailbase-storage.yml

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: trailbase-storage
   spec:
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
   
2. Create Deployment

   trailbase-deployment.yml

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: trailbase-deployment
     labels:
       app: trailbase
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: trailbase
     strategy:
       type: Recreate
     template:
       metadata:
         labels:
           app: trailbase
       spec:
         containers:
           - name: trailbase
             image: docker.io/trailbase/trailbase:latest
             ports:
             - containerPort: 4000
             env:
             - name: RUST_BACKTRACE
               value: "1"
             volumeMounts:
               - name: trailbase-storage
                 mountPath: /app/traildepot
         restartPolicy: Always
         volumes:
           - name: trailbase-storage
             persistentVolumeClaim:
               claimName: trailbase-storage
   
3. Create Service

   trailbase-service.yml

   apiVersion: v1
   kind: Service
   metadata:
     name: trailbase-service
   spec:
     selector:
       app: trailbase
     ports:
       - protocol: TCP
         port: 4000
         targetPort: 4000
   
4. Deploy to cluster

   kubectl apply -f trailbase-storage.yml
   kubectl apply -f trailbase-deployment.yml
   kubectl apply -f trailbase-service.yml
   

The Kubernetes deployment uses a Recreate strategy to ensure only one pod writes to the database at a time, as SQLite does not support concurrent writes from multiple processes.

Podman Support

TrailBase images also work with Podman:

# Using Podman play kube with the deployment manifest
podman play kube trailbase-deployment.yml --publish=4010:4000

# Check running containers
podman ps

# View logs
podman logs trailbase-deployment-pod-trailbase

For persistent storage with Podman:

# Create a named volume
podman volume create trailbase-storage

# Or use a bind mount with proper permissions
podman play kube trailbase-deployment.yml --userns=keep-id

Building Custom Images

To build a custom TrailBase Docker image:

1. Clone the repository

   git clone https://github.com/trailbaseio/trailbase.git
   cd trailbase
   git submodule update --init --recursive
   
2. Build the image

   docker build -t trailbase:custom .
   

   The Dockerfile uses multi-stage builds:

   • builder: Compiles Rust code with MUSL for static linking
   • auth-ui-builder: Builds auth UI WASM component
   • binary-builder: Builds the main TrailBase binary
   • image: Final Alpine-based image with minimal dependencies
3. Run your custom image

   docker run -d -p 4000:4000 -v ./traildepot:/app/traildepot trailbase:custom
   

Health Checks

The Docker image includes a built-in health check:

HEALTHCHECK CMD curl --fail http://localhost:4000/api/healthcheck || exit 1

Use this in docker-compose:

docker-compose.yml

services:
  trail:
    image: docker.io/trailbase/trailbase:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4000/api/healthcheck"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Or override it:

services:
  trail:
    image: docker.io/trailbase/trailbase:latest
    healthcheck:
      disable: true

Production Recommendations

Use specific image tags

Avoid using :latest in production. Pin to specific versions:

services:
  trail:
    image: docker.io/trailbase/trailbase:v0.1.0

Set resource limits

Define CPU and memory limits:

services:
  trail:
    image: docker.io/trailbase/trailbase:latest
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 256M

Enable logging

Configure log rotation:

services:
  trail:
    image: docker.io/trailbase/trailbase:latest
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Use secrets for sensitive data

Store sensitive configuration in Docker secrets:

services:
  trail:
    image: docker.io/trailbase/trailbase:latest
    secrets:
      - smtp_password
    environment:
      TRAIL_EMAIL_SMTP_PASSWORD_FILE: /run/secrets/smtp_password

secrets:
  smtp_password:
    external: true

Troubleshooting

Permission Denied Errors

If you see “Permission denied” errors in logs:

# Fix ownership of data directory
sudo chown -R 1000:1000 traildepot/

# Or run container as root (not recommended)
docker run --user root trailbase/trailbase:latest

Container Won’t Start

Check logs for errors:

docker logs trailbase
# or
docker-compose logs trail

Database Locked

SQLite databases can’t be accessed by multiple containers:

# Ensure only one container is running
docker ps | grep trailbase

# Stop all TrailBase containers
docker stop $(docker ps -q --filter ancestor=trailbase/trailbase)

Next Steps

Production Setup

Production checklist, security hardening, and monitoring

Configuration

Detailed configuration options and environment variables