Docker Compose

Docker Compose provides the easiest way to run HitKeep with persistent storage and networking pre-configured.

Security Best Practice

We recommend passing sensitive values (like HITKEEP_JWT_SECRET) via Environment Variables rather than command flags to prevent them from leaking in logs or inspection commands.

Quick Start

Create a compose.yml file:

services:
  hitkeep:
    image: ghcr.io/pascalebeier/hitkeep:latest
    container_name: hitkeep
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - hitkeep_data:/var/lib/hitkeep/data
    environment:
      # Securely pass secrets via ENV vars
      - HITKEEP_JWT_SECRET=change-me-to-a-long-random-string
    command:
      # General config via flags
      - "-public-url=http://localhost:8080"

volumes:
  hitkeep_data: {}

Run it:

docker compose up -d

Reverse Proxy Configurations

HitKeep runs on port 8080 by default. For production, you should run it behind a reverse proxy to handle HTTPS (SSL).

Caddy

Caddy handles automatic HTTPS certificates (Let’s Encrypt) for you.

services:
  caddy:
    image: caddy:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - caddy_data:/data
      - caddy_config:/config
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - hitkeep_net

  hitkeep:
    image: ghcr.io/pascalebeier/hitkeep:latest
    restart: unless-stopped
    networks:
      - hitkeep_net
    volumes:
      - hitkeep_data:/var/lib/hitkeep/data
    environment:
      - HITKEEP_JWT_SECRET=change-me-securely
    command:
      - "-public-url=https://analytics.example.com"

volumes:
  caddy_data: {}
  caddy_config: {}
  hitkeep_data: {}

networks:
  hitkeep_net:

Caddyfile:

analytics.example.com {
  reverse_proxy hitkeep:8080
}

Traefik

If you are running a Traefik stack, use labels to expose HitKeep.

services:
hitkeep:
image: ghcr.io/pascalebeier/hitkeep:latest
restart: unless-stopped
volumes:
- hitkeep_data:/var/lib/hitkeep/data
environment:
- HITKEEP_JWT_SECRET=change-me-securely
command:
- "-public-url=https://analytics.example.com"
labels:
- "traefik.enable=true"
- "traefik.http.routers.hitkeep.rule=Host(`analytics.example.com`)"
- "traefik.http.routers.hitkeep.entrypoints=websecure"
- "traefik.http.routers.hitkeep.tls.certresolver=myresolver"
- "traefik.http.services.hitkeep.loadbalancer.server.port=8080"

volumes:
hitkeep_data: {}