Docker Compose configuration for the Pterodactyl Panel.
Pterodactyl is an open-source control panel used for hosting numerous game-related services, such as Minecraft and Teamspeak servers. Setting it up, however, takes quite a few steps according to the documentation.
This Docker Compose configuration is aimed at removing a majority of the steps so
that the installation process is almost as simple as cloning this build script and
running docker-compose up.
There are other Docker Compose setups available, including the one created by one of the project's primary developers, parkervcp. This differs from those setups in various ways for a couple of different reasons:
- This setup splits the HTTP and PHP services into two different containers. Doing so allows for separation of concerns (a central Docker principle) and easier management of containers and Dockerfiles.
- This setup uses Nginx instead of Caddy. Various benchmarks indicate that Nginx performs better than Caddy in handling requests. In addition to this, Nginx, while having a more complicated configuration file, doesn't enforce HTTPS, a feature of Caddy which only complicates the setup of the HTTP Docker container.
version: "3.1"
services:
mariadb: # for minecraft servers
image: mariadb
restart: unless-stopped
container_name: main_mysql
expose:
- 3306
environment:
- "MYSQL_DATABASE=db"
- "MYSQL_PASSWORD=pterodactyl"
- "MYSQL_RANDOM_ROOT_PASSWORD=yes"
- "MYSQL_USER=pterodactyl"
volumes:
- db:/var/lib/mysql
networks:
pterodactyl_nw:
ipv4_address: 172.254.0.254
default:
volumes:
db:
networks:
pterodactyl_nw:
external: true
and the database address is 172.254.0.254, port is 3306. check logs for the root password.
The instructions are fairly self explanatory: clone the repository and launch the project. Instructions on how to launch the project are listed below. All commands should be run from the repository directory.
In your favorite text editor, open docker-compose.yml change the port that you want the panel binded to. See below for more details. Once that's done, build and start the project.
docker-compose -p <project_name> pull
docker-compose -p <project_name> build
docker-compose -p <project_name> up
The panel is now online. If this is your first time booting the panel, you'll also need to run the install script, which will run all of the necessary configuration scripts and database migrations for you.
docker exec -it <project name>_php_1 install
# Restart the panel to load changes. The install script will remind you to do so.
docker restart <project name>_php_1
The panel should now be ready, and you can connect to it via localhost at the port you specified in the Docker Compose file.
To set the port for the HTTP server, adjust the setting under services, http, and ports:
<host port number>:80
Two scripts are provided in order to aid with installation and upgrades.
# Use these scripts with the following command:
docker exec -it <project name>_php_1 <script name>
- install: Runs all the installation scripts, including migrations and configuration.
- upgrade: Runs all the steps needed to upgrade to the latest version of the panel.
Note that depending on how old your version of the panel is, the upgrade command may not work. Be sure to check the changelog for each release and make sure your version is not listed as not working.
Always remember to back up your data before upgrades! While I do my best to keep this Docker Compose configuration stable, there is always the chance that something can go horribly wrong! See the next section on how to run backups.
Upgrading the project is slightly more complex. See the second caveat for an explanation as to why.
To upgrade, take down the project and wipe out the panel volume as it interferes with the upgrade process.
docker-compose -p <project name> down
docker volume rm <project name>_panel
Rebuild and restart the project.
docker-compose -p <project name> pull
docker-compose -p <project name> build
docker-compose -p <project name> up
Finally, run the upgrade script.
docker exec -it <project name>_php_1 upgrade
# Restart the panel to load changes. The upgrade script will remind you to do so.
docker restart <project name>_php_1
The volumes that you will need to backup are db (database), env (configuration),
and storage (stored eggs and other files). These commands only work when the project
is up (a caveat of Docker).
# Use mysqldump to back up the database.
docker exec -it <project name>_db_1 mysqldump -u pterodactyl -ppterodactyl pterodactyl > database.sql
# You can copy the .env file from the mounted env volume.
docker cp <project name>_php_1:/var/www/html/env/.env .env
# You can copy the mounted storage volume.
docker cp <project name>_php_1:/var/www/html/pterodactyl/storage storage
- Due to the need for a .env file early on in the build process, it is impossible to automatically run an install script, which would depend on checking for the existence of a .env file. You will need to manually run the install and upgrade scripts as necessary. Their use has been covered in the previous section.
- The panel volume is required to share data between the HTTP and PHP containers, but the existence of this volume interferes with upgrade files due to how Docker works. These containers are separated for reasons already outlined, but this does mean that this volume must manually be removed on each upgrade.
- A symbolic link is used to maintain the state of the .env file rather than Docker configs because of issues with Docker itself. Configs exist, but because they are read-only filesystems, they cannot be modified in the container, making their maintenance much more complicated. They would also require the use of Docker Swarms and Docker Services.
- This setup is for Docker Compose, not for Docker Swarm or Docker Service. These two Docker services take much more convoluted configuration, including the setup of a swarm and the use of a local image registry, which would only complicate this setup.