Docker Deployment

Introduction

The Panel image runs the whole Panel in one container: NGINX, PHP 8.4, the queue worker, and the scheduler. You provide the database and Redis; Wings and game servers run on your nodes.

Before you start, read the requirements.

Choosing an Image

Always deploy a specific version tag or digest. The example Compose file uses ghcr.io/pterodactyl/panel:latest, which does not point to 2.0 until 2.0 is released.

To build the image yourself, run this from a 2.0 source checkout:

docker build --pull -t pterodactyl-panel:2.0-local .

Copy docker-compose.example.yml to compose.yaml. If you built the image yourself, set the panel service's image to pterodactyl-panel:2.0-local. Review APP_URL, the database credentials, mail settings, ports, and mounted paths.

The example uses MariaDB 11.4 and Redis 7.4. These settings control the services inside the Panel container:

Setting	Effect
`QUEUE_WORKER_ENABLED`	Set to `true` to run the queue worker.
`SCHEDULER_ENABLED`	Set to `true` to run the scheduler. Enable it on only one Panel container.
`CACHE_STORE=redis`	Stores the cache in Redis.
`SESSION_DRIVER=redis`	Stores sessions in Redis. Use it with `SESSION_CONNECTION=sessions`.
`QUEUE_CONNECTION=redis`	Stores queued jobs in Redis.
`APP_ENVIRONMENT_ONLY=true`	Reads Panel settings from the environment instead of the database.

QUEUE_WORKER_ENABLED and SCHEDULER_ENABLED must be exactly true or false.

The container runs the queue worker and scheduler itself. Do not also set up the pteroq service or the cron entry from Getting Started.

Persistent Data

The example Compose file keeps these paths outside the container:

Path	Contents
`/app/var`	The `.env` file, including `APP_KEY` and `HASHIDS_SALT`
`/etc/nginx/http.d`	NGINX configuration
`/etc/letsencrypt`	TLS certificates
`/app/storage/logs`	Panel logs
`/app/extensions`	Installed extensions
`/app/public/assets/extensions`	Extension assets
`/var/lib/mysql` in the database container	The Panel database
`/data` in the Redis container	Redis data

On first start, the container creates /app/var/.env with new keys, and reuses it when you recreate the container.

Back up the database and /app/var/.env together. All Panel containers must share the same APP_KEY and HASHIDS_SALT. Never generate new keys for an existing Panel.

Game server files and their backups live on your Wings nodes, not in these volumes.

Running Migrations

The container does not migrate the database on start. Run migrations yourself, once per deployment, before the new version serves traffic. That way, starting an extra container never changes your database.

For a new installation, start the database and Redis, migrate, create your first administrator, then start the Panel:

docker compose -f compose.yaml up -d database cache
docker compose -f compose.yaml run --rm panel php artisan migrate --seed --force --no-interaction
docker compose -f compose.yaml run --rm panel php artisan p:user:make
docker compose -f compose.yaml up -d panel

These steps are for new installations only. Moving an existing 1.x database into this image is not tested yet. To upgrade a native 1.x installation, see Upgrading From 1.x.

HTTPS

To get a Let's Encrypt certificate, set APP_URL to your https:// address, set LE_EMAIL, and keep /etc/letsencrypt on a volume. Your domain must reach the container on port 80.

If a reverse proxy handles HTTPS, leave LE_EMAIL empty. Send the proxy's traffic to the container's HTTP port, and configure the Panel's trusted proxies.

Wings

The Compose file does not run Wings or give the Panel access to Docker. Install Wings separately on each node.

The Panel and Wings may share a machine. Game servers run in their own images, chosen by each egg, and those images must support your node's CPU architecture. An ARM64 Panel image does not mean every game supports ARM64.