The joys of setting up Pterodactyl

How I set up my pterodactyl panel and the issues I discovered (and solved) along the way.

An image that looks similar to minecraft, I guess?
Photo by Toby56 / Unsplash

A story of the tutorial, strange networking, DNS and CORS.

Some time ago (in the spring of 2022), I was tight on cash and expanding my homelab, and offered my friend a deal. He gives me cash upfront to buy more ram, I host him a Minecraft server on my homelab.

This seemingly easy task slowly morphed into a machination I needed ~3 days to completely set up, the main reason for that being feature creep.

So, I went ahead and bought the ram, and then forgot all about the deal for a few months, while I was focusing on my finals. Come end of the finals season, I realize I owe my friend my part of the deal and reach out to him for the specifics. He says he needs a bit more ram than first agreed to and some other things, and I realize this isn't that small of a task. I go and look into different game management panels, thinking it would solve most of my problems as I wouldn't have to manage his servers for him.

The two that I found at the time I was deciding were PufferPanel and Pterodactyl panel. In the end I settled on Pterodactyl, but I honestly don't remember why anymore. There were probably good reasons? In case others want to try something similar, do check out PufferPanel as well.

Pterodactyl is an open-source game server management panel built with PHP, React, and Go. Designed with security in mind, Pterodactyl runs all game servers in isolated Docker containers while exposing a beautiful and intuitive UI to end users.
Link to the project's website.


Pterodactyl consists of two different services: the panel, served on a web server and the Wings nodes. The actual game servers are hosted on the Wings nodes, with the panel providing only the UI for managing them and the user database. The game servers themselves are isolated in docker containers, controlled by the wings daemon, which is controlled by the panel. When set up properly, the panel can automatically update wings' configurations.

The panel lights up... but the server doesn't?
(and the awesome community support!!)

I set up the panel and the wings node without any issues, which was a huge surprise for me! The documentation for Pterodactyl was surprisingly good and, provided you're familiar with the Linux command line (as stated in the documentation itself), very straight forward. To test that everything actually worked, I decided to install a Minecraft paper server, but the installation was taking very long.

After a bit of digging with systemctl status wings.service I figured out it had something to do with the containers for the servers. My first thought was that it had something to do with me running the wings node in a LXC container and that there were some unsupported edge-cases. I did some basic tests and determined I am indeed able to pull an alpine and ubuntu image on my host and that both work without any issues (they both had working interactive bash shells with -it). After determining everything on my side definitely works correctly I finally gave in and decided to ask others for help. On the main Pterodactyl page I found a "get help" button and decided to click it. It took me to their community discord server!

Join the Pterodactyl® Discord Server!
Pterodactyl makes running game servers at scale painless. Make server hosting a first-class citizen on your platform. | 21,834 members
Many thanks to the folks in the Pterodactyl discord server!

Immediately after I asked my question I got an automated response from the bot that was actually helpful for once, and was asked to use a script to automatically upload my logs to their pastebin. That, too, worked flawlessly. I quickly also got a response from a user on the server, who quickly enlightened me as to the cause of my troubles. As it turns out, just when I was testing if the minecraft server works, the github container registry had an outage, and as the wings service always checks for a newer version, it stalled every time. Had I tried installing the server at any other time, it would have worked without a hitch!

It works! (on my machine...)

After resolving the previous issue, I successfully booted up the minecraft server, tested that it works, checked the panel, made a user account for my friend and gave him access.

Some time after, I got a call from him telling me the server's console exposed on the panel actually doesn't work. I was quite certain it worked just hours before and that it couldn't just break so early. I thought for a bit and then realized my issue. I was testing pterodactyl on my local network, but only quickly checked it works exposed to the internet. I tested it again, and was presented with the same error he also had: "We're having some trouble connecting to your server, please wait..."

After doing some digging in the F12 browser console, I discovered the issue: the pterodactyl panel was requesting data from the wings node, on the wings node's local IP, which I set up when I was quickly setting up the server. I thought to myself, that's an easy fix! Just make a few DNS entries and blam! it works!

It doesn't work. (What's a CORS?)

And then it didn't work. Not on the local network, not on the public internet. As it turns out, Pterodactyl automatically updates the wings' configuration files, if it's able to do so. Due to me messing with the DNS entries and server hostnames, the configuration files couldn't be delivered. (The panel was sending the config to a not-yet-existent server, or the server didn't accept the config, as the keys had changed.) Sometimes, the wings node showed up inconsistently, seemingly random.

The issue was actually two-fold. The first part was that the config wasn't uploading due to one reason or another and I was able to solve it by just updating the config manually. (it is stored in /etc/pterodactyl/config.yml)

The second part of the issue was, to me, way harder to diagnose and solve. Sometimes, the server showed up with a heartbeat, other times it didn't. After some digging around in the web console when it didn't show up (F12 -> debug in Firefox), I noticed a few strange errors I had never seen before, namely about CORS (Cross-Origin Resource Sharing). (It's worth noting here that webdev isn't my area of expertise and such digging around in the web console is uncommon for me.)

illustration of how CORS works.
What CORS even is and how it works (Image taken from

After some searching around the internet and experimenting, I figured out what the error is telling me. The heartbeat showed up normally when requested from a certain domain, and didn't show up at all when requested from a different domain (a refferal domain), the specified domain being the one that made the config file that was uploaded to the wings node.

I fixed that by clearly specifying which domain the server is being accessed from and only using that domain (only accessing the panel on a single domain and never on its own IP address) and by dual-homing the DNS entries for the servers, ensuring they resolve properly to their LAN addresses on the LAN and to the public IP on the WAN.

It finally works!

And that's basically it. Even though some of the problems were particularly hard to diagnose, looking back on the project, it went very well and I expected a lot more hitches, mostly to do with the install of Pterodactyl and Wings themselves, not with the surrounding deployment environment. So far, after a week of using Pterodactyl panel and Wings, I must say I am happy with the platform they provide and that the support on their discord server was stellar.

If you enjoyed reading the post and are interested in reading more from me, please do subscribe below! It means a lot to me seeing people actually reading this and finding good uses for it. Currently I have a few more projects planned to post about here!