Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/calagopus/panel/llms.txt

Use this file to discover all available pages before exploring further.

This guide gets a working Calagopus panel running on your machine using Docker Compose. The Compose file bundles the panel, PostgreSQL, and Valkey so no separate database setup is needed.
Before you start, make sure Docker and Docker Compose are installed on your server. Calagopus requires Docker Compose v2 or later.

​
Deploy with Docker Compose

1

Download the Compose file

Download the official compose.yml to a directory of your choice, such as /opt/calagopus.
mkdir -p /opt/calagopus && cd /opt/calagopus
curl -O https://raw.githubusercontent.com/calagopus/panel/main/compose.yml
The file defines three services: the panel (web), a PostgreSQL database (db), and a Valkey cache (cache).
compose.yml
services:
  web:
    image: ghcr.io/calagopus/panel:latest
    restart: unless-stopped
    environment:
      - TZ=Europe/Berlin
      - REDIS_URL=redis://cache
      - DATABASE_URL=postgresql://panel:panel@db/panel
      - DATABASE_MIGRATE=true
      - PORT=8000
      - APP_DEBUG=false
      - APP_LOG_DIRECTORY=/var/log/calagopus
      - APP_PRIMARY=true
      - APP_ENABLE_WINGS_PROXY=true
      - APP_ENCRYPTION_KEY=CHANGEME
      - APP_USE_DECRYPTION_CACHE=true
      - APP_USE_INTERNAL_CACHE=true
    volumes:
      - ./data:/var/lib/calagopus
      - ./logs:/var/log/calagopus
    ports:
      - 8000:8000
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on:
      - db
      - cache

  db:
    image: ghcr.io/calagopus/pgautoupgrade:18-alpine
    restart: unless-stopped
    environment:
      - TZ=Europe/Berlin
      - POSTGRES_USER=panel
      - POSTGRES_PASSWORD=panel
      - POSTGRES_DB=panel
      - PGDATA=/data
    volumes:
      - ./postgres:/data

  cache:
    image: ghcr.io/calagopus/valkey:latest
    restart: unless-stopped
    command: --protected-mode no --save 60 1
    environment:
      TZ: Europe/Berlin
    volumes:
      - ./cache:/data
2

Set a secure encryption key

Open compose.yml and replace the APP_ENCRYPTION_KEY value with a random secret. This key encrypts sensitive data such as node daemon tokens and database host passwords. It cannot be changed after the panel is started without losing access to encrypted records.
- APP_ENCRYPTION_KEY=CHANGEME   # replace with a strong random secret
Generate a suitable value with:
openssl rand -hex 32
Never leave APP_ENCRYPTION_KEY set to CHANGEME in production. Store this value somewhere safe — it cannot be recovered if lost.
3

Start the panel

From the directory containing compose.yml, run:
docker compose up -d
Docker pulls the images and starts all three services. The web service runs database migrations automatically on first boot (DATABASE_MIGRATE=true). Wait a few seconds for migrations to complete before proceeding.Check the logs if the container does not come up as expected:
docker compose logs -f web
4

Create an admin user

Use the panel CLI to create your first administrator account. The command runs interactively and prompts for username, email, name, password, and admin status.
docker compose exec web panel users create
To create a user non-interactively, pass all arguments on the command line:
docker compose exec web panel users create \
  --username admin \
  --email admin@example.com \
  --name-first Admin \
  --name-last User \
  --password "your-password" \
  --admin true
5

Open the panel

Navigate to http://your-server-ip:8000 in your browser and log in with the credentials you just created.
For production deployments, place a reverse proxy such as nginx or Caddy in front of the panel and terminate TLS there. See the reverse proxy guide for configuration examples.

​
Environment variable reference

The following variables in compose.yml should be reviewed before deploying.
VariableDefaultDescription
APP_ENCRYPTION_KEYCHANGEMERequired. Secret key used to encrypt sensitive values at rest.
TZEurope/BerlinTimezone for the panel and database containers.
PORT8000Port the panel HTTP server listens on inside the container.
APP_PRIMARYtrueMarks this instance as responsible for background tasks (cleanup, schedules). Set to false on replica instances.
APP_ENABLE_WINGS_PROXYtrueProxies client WebSocket connections through the panel to Wings. Useful for home networks; disable for high-traffic multi-node setups.
APP_USE_DECRYPTION_CACHEtrueCaches decrypted values in memory and Redis for better performance.
APP_USE_INTERNAL_CACHEtrueCaches short-lived values in application memory in addition to Redis.
APP_DEBUGfalseEnables verbose debug logging. Do not enable in production.

​
Wings compatibility

Calagopus is fully compatible with existing Pterodactyl Wings nodes. Add your Wings nodes from Admin → Nodes without reinstalling or reconfiguring the Wings daemon.

​
Next steps

Full installation guide

Detailed installation with reverse proxy setup, TLS, and production hardening.

Migrate from Pterodactyl

Import users, servers, nodes, and eggs from an existing Pterodactyl panel.

Build docs developers (and LLMs) love

Get started for freeTalk to us