Development using Docker

This approach offers several advantages compared to Vagrant:

• Faster boot and initial setup times
• Easy viewing & resetting of server data
• Lower resource consumption
• Easy service management & viewing of logs

Prerequisites

• Latest version of NodeJS LTS
• pnpm (npm install -g pnpm@latest)
• Git
• Docker Engine
  • On Linux, see your distro's wiki or Docker's docs for setting up Docker alongside its services
  • On macOS, OrbStack is recommended to provide Docker Engine, but Docker Desktop can be used instead
  • If using Docker Desktop on macOS, install docker-mac-net-connect
• buildx and compose Docker extensions
  • These are installed by default with OrbStack and Docker Desktop

Limitations

• Rootless Docker (Linux) is not supported
• To delete or modify server data on Linux, you'll need to use sudo as Docker creates the volume binds as root
• If you move the repositories location, you'll need to reset the server data as paths are hardcoded in the container

Initial setup

1. Clone the Pyrodactyl panel repository

2. Install dependencies:

   pnpm i

3. Build the project:

   pnpm run ship

   • Caches build results
   • Uploads sourcemaps to Sentry
   • Makes subsequent builds without code changes nearly instant

4. Initialize the Docker image: pnpm build:docker:dev

   • Installs PHP and system dependencies
   • Configures the image for Pyrodactyl services
   • This only needs to be done once unless PHP dependencies or the Dockerfile changes

5. Copy the docker-compose.develop.yml file to docker-compose.yml, and adjust it carefully if needed

6. Move onto general usage

General usage

Once you've completed the initial setup:

1. Run pnpm compose to startup the environment. If this is your first time running this, it'll take a second to pull and configure everything

2. Run pnpm dev:docker to start a local development server

   • For a production preview, run pnpm run ship and its build will be hosted by Docker

3. Access Pyrodactyl from http://localhost:3000/, and login using the default credentials of [email protected] and password

4. Once finished, you can stop Docker using pnpm compose:down

Tips

Remote caching

Set up Remote Caching via Turbo for faster builds. Cached results allow production server builds to complete in milliseconds.

Database host

This method supports creating a database host out of the box, which allows you to create databases on servers for testing. To do this, navigate to http://localhost:3000/admin/databases, click Create New, and use the following settings:

Name: db                      # you can name it anything
Host: database                # the name of the database service in Docker
Port: 3306                    # leave it at default
Username: pterodactyluser
Password: somepassword
Linked node: local

Resetting server data

To irreversibly reset your Docker data:

1. Take the Docker compose down (pnpm compose:down)

2. Enter the following command in your terminal (sudo is only required on Linux):

   sudo rm -rf var vendor .env srv

3. Put the Docker compose back up again (pnpm compose) and server data should be recreated

Troubleshooting

Make sure you're not running into any known limitations.

General errors

Firstly, try the below:

1. Ensure your docker-compose.yml is correct. You should've copied the example docker-compose.develop.yml to this file
2. Reset your server data if your happy to do so
3. Rebuild the Docker image (pnpm build:docker:dev)

If nothing above works, collect any errors from the following to aid in troubleshooting:

• The latest Laravel logs inside ./srv/logs
• The logs of the services (i.e. panel, Wings, database)

You can try searching these errors in the Pterodactyl Discord server as someone has likely already found a solution. However, DO NOT ask for support in the Pterodactyl Discord as they do not support Pyrodactyl and will not help you.

If you need to ask for help, ask in our Pyrodactyl Discord server.

Ports in use

Try killing any processes that could be using Pyrodactyl's ports, i.e. 8080, 2022, and 3000 by default, then run pnpm compose again. However, if that won't work, try the below:

1. If the issue is while starting a server, adjust the allocations in your node settings to other ports
2. If the issue is while starting the compose, carefully adjust the docker-compose.yml's IP settings