Local Development

There are three ways to set up a local development environment for Pyrodactyl:

• Using Nix on Linux (recommended for faster performance)
• Using Vagrant on Linux (traditional VM-based approach)
• Using Vagrant on Windows (first Pterodactyl panel with Windows development support)

Local Dev with Nix

This approach offers several advantages:

• Faster boot times without VM overhead
• Lower resource consumption
• Flexible configuration through nix/buildsteps.sh
• Improved reliability across Linux distributions

Prerequisites for Nix Setup

• Nix Package Manager
• NodeJS (latest LTS version)
• Docker Engine
• Git

Getting Started with Nix

1. Install Nix and enable flakes support (configuration varies by distribution)

2. Clone the Pyrodactyl panel repository

3. Install dependencies:

   npm i

4. Build the application:

   npm run ship

   This step:

   • Caches build results
   • Uploads sourcemaps to Sentry
   • Subsequent builds are much faster if code hasn't changed

5. Create environment file:

   cp .env.nix .env

6. Initialize development environment:

   nix run

Nix Setup Process

The initialization process is completely automated:

• Sets up Wings and required services
• Configures databases and application
• Takes approximately 15 minutes

Once you see "Pyrodactyl is now up and running at localhost:8000", access the application and login using the credentials shown in your console.

Visit http://localhost:8000/admin to create your first server.

Known Issues with Nix

Local Dev with Vagrant on Linux

Prerequisites for Vagrant Setup

• NodeJS (Latest LTS version)
• Git
• Vagrant
• libvirtd
• nfs-utils

Installing NFS Utils

For Fedora:

sudo dnf install nfs-utils

For Ubuntu/Debian:

sudo apt-get install nfs-kernel-server

Enable and start the NFS server:

# Start the service
sudo systemctl start nfs-server
 
# Enable on boot
sudo systemctl enable nfs-server

Development Setup with Vagrant

1. Clone the Pyrodactyl panel repository

2. Install dependencies:

   npm i

3. Build the project:

   npm run ship

   This step:

   • Caches build results
   • Uploads sourcemaps to Sentry
   • Subsequent builds without code changes are nearly instant

4. If using libvirt, install the vagrant-libvirt plugin

5. Initialize the environment:

   vagrant up

   This process:

   • Sets up wings and required services
   • Configures databases and applications
   • Takes approximately 15 minutes

6. Access Pyrodactyl at localhost:3000 and login with the console-provided credentials

Troubleshooting Vagrant Setup

VM Configuration

When using alternatives to libvirtd, modify the Vagrantfile to allocate more than the default 512MB RAM

NFS Mount Error

If you encounter a "Connection refused" error during first vagrant up, simply retry the command

Permission Issues

Run commands with sudo:

sudo vagrant up

Local Dev with Vagrant on Windows

Pyrodactyl is the world's first Pterodactyl panel that can be developed and run locally (with Wings) on Windows machines through Vagrant.

Prerequisites for Windows

• NodeJS (latest LTS version)
• Vagrant
• Git

Installing on Windows

1. Clone the Pyrodactyl panel repository

2. Install dependencies:

   npm i

3. Build the application:

   npm run ship

   This step:

   • Caches build results
   • Uploads sourcemaps to Sentry
   • Subsequent builds are much faster if code hasn't changed

4. Initialize the environment:

   vagrant up

   This process:

   • Sets up Pterodactyl Wings and necessary services
   • Configures databases and applications
   • Takes approximately 15 minutes

5. Login using the credentials shown in your console

6. Visit http://localhost:8000/admin to create your first server

Development Notes

Development Server

• Running npm run dev serves a development build at localhost:3000 with Hot Module Replacement (HMR)
• For production preview:
  1. Stop the dev server
  2. Run npm run ship
  3. Access http://localhost:3000

Troubleshooting Connection Issues

• If localhost:3000 hangs indefinitely:
  1. Check for port conflicts with other applications (e.g., Steam using port 8080)
  2. After resolving conflicts, run vagrant reload to reset port mappings

VirtualBox Shared Folders

If encountering "Vagrant was unable to mount VirtualBox shared folders":

# Install vbguest plugin
vagrant plugin install vagrant-vbguest
 
# For existing installations, update with:
vagrant plugin update vagrant-vbguest

Performance Tips

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

Virtualization Notes

• Recommended: VMWare Workstation or VirtualBox
• If prompted for password with Hyper-V, use your Windows credentials