Pterodactyl Docker

Pterodactyl is an open-source game server management panel built with PHP 7, 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. Stop settling for less.

"Make game servers a first-class citizen on your platform."

Please read our disclaimer https://docs.ibracorp.io/#disclaimer.

Assumptions

You have the community apps installed within Unraid
You are running Nginx Proxy Manager or Traefik as your reverse proxy
You have set up SSL Certificates and added them to your Nginx Proxy Manager
You are using Cloudflare as your DNS provider and have all your subdomains proxied
You have MariaDB set up and running
You have Adminer running on your system
You will be installing Redis (below)

Pterodactyl Docker Containers

Pterodactyl docker containers are split into two containers. One container is for the panel where everything is controlled and the other is the daemon, where the actual containers are created and maintained. First we are going to set up a few things before we get into the actual installation.

Now before we install anything we need to set up a file share for where we are going to store not only all the config files but also all of the game server data. Depending on how many game servers you would like to store/run, this could take up quite a bit of space. For best performance I would suggest storing this data on your cache drive, if you do not have enough space then you will have to store this on your array.

In this example, we will be calling this file share "pterodactyl-node" and asking the system to move all files to the "cache" by choosing "Prefer" in the Use cache pool dropdown.

By default Unraid 6.9.2 and below sets the default security of this share to be publicly accessible. It is good practice to lock this down with either "Secure" or "Private".

Pterodactyl Database

Before we can install the Pterodactyl Panel from the community apps template we need to make sure we have a database and user set up ready for it to use.

For this example, we will be using the following information to create the database

Database Name: pterodactyl
Database Username: pterodactyl
Database Password: SomeSuperSecurePassword

If you do not know how to create a database in MariaDB using Adminer then we suggest following along with this video for this step.

Redis cache

In Pterodactyl Panel update v1.8.0 using a redis cache is no longer optional, and is now required for the panel to operate.

It is recommended to use the official redis container (maintained in unraid by jj9987)

Once created, you'll have to add a new variable to the Pterodactyl Panel container like this

Cloudflare

We are first going to create our subdomains in cloudflare.

In this example, we will be using Cloudflare to proxy our traffic to our panel server.

In this other example, we will also be using Cloudflare to proxy our traffic to our node server.

NPM Reverse Proxy

Pterodactyl Panel

Now since we are setting up a gaming server it's safe to assume you would like to play this with your friends online. It is also useful for your friends to be able to access the panel and maintain the gaming servers if you so wish. To do this we will add the panel to your reverse proxy of choice, for this example, we will be using Nginx Proxy Manager.

For the scheme, we will be using http , for the IP we will be using our Unraid IP (in this example we will be using 192.168.60.20) and for the port, we will use the port we mapped in the template to the container port 80 (in this example we will use port 8001).

To make sure that the connection is secure we will also be adding our cert to the proxy host configuration. Click on the SSL tab and set this up how you usually add your certs. Only enable HSTS if you have this enabled on your Cloudflare.

Pterodactyl Node

Now for the two containers to be able to talk to each other securely through https we are going to set up another CNAME record with a subdomain for the panel to talk to the daemon container. For this example we will call it the node app.

For the scheme we will be using http , for the IP we will be using our Unraid IP (in this example we will be using 192.168.60.20) and for the port we will use the port we mapped in the template to the container port 80 (in this example we will use port 8181).

Traefik Reverse Proxy

If you are using Traefik as a reverse proxy then add the following in fileConfig.yml

# Pterodactyl corsALL
corsAll:
  headers:
    customRequestHeaders:
      X-Forwarded-Proto: "https"
    customResponseHeaders:
      X-Forwarded-Proto: "https"
    accessControlAllowMethods:
      - OPTION
      - POST
      - GET
      - PUT
      - DELETE
    accessControlAllowHeaders:
      - "*"
    accessControlAllowOriginList:
      - "*"
    accessControlMaxAge: 100
    addVaryHeader: true

The following image is where the file is supposed to be at.

Now, if you are using fileConfig.yml to proxy your containers instead of labels then the following image example would add the corsAll middleware to the Pterodactyl panel and node.

Installing the Panel

Now we are ready to install the Pterodactyl Panel docker container. Head over to the community apps and search for Pterodactyl. You will find a few containers but to keep things simple, let's only use the Sycotix containers.

We should be able to leave all the fields their default value and should only have to adjust the available port for the web user interface and the database user password.

Here you will choose your custom docker network, if you have not made one yet you can watch this video here on how to create one.
You will need to select a port that is free for the Pterodactyl WebUI. In this example we will user 8001.
Here we need to add the pterodactyl share that we created earlier to store all of the shared config files and game server files etc.
Here we will set our local time zone so that the container is in sync.
Depending on how you have your MariaDB container set up, you should be able to add the container name here (mariadb) to be able to access the container. If it is not on the same docker network then you will have to use the Unraid IP address.
We now need to select the default port for MariaDB. Since this example is using the internal hostname for MariaDB we will be adding the internal container port here 3306 but if you used the server IP, then you will have to add whatever port you mapped the MariaDB container to.
For this example we will call the new database for the Pterodactyl set up pterodactyl . If you are unsure of how to set up a database then follow this video here.
Now we need to add the database user so that Pterodactyl can access the database. If you are unsure of how to add a user to an existing database then you can watch this video.
To authenticate the database user you will also have to add the password you set up when adding the user. Again, this is covered in this video if you are unsure.
We are not expecting any issues so we will not start the container in Debugging mode. If you do encounter any issues it would be a good place to start to enable this and restart the container. It should give you more valuable logs to work from.
This is where we will map the game data folder from the container to our new folder share that we set up.
The container has a few config files that are useful to have stored on the host so that they are persistent after container rebuilds. we will also be mapping this to the new Pterodactyl share we created earlier.
Click apply to deploy the container.

Once you click apply, the docker image should now be pulled and started and your panel should now be running.

Adding the First Admin User

We will now run a command to make your first admin account for the panel. From within the Unraid console, paste in the following command and follow the steps:

docker exec -it pterodactyl-panel php artisan p:user:make

It will now ask you a series of questions to create the first administrator user.

You should now be able to visit the panel by clicking the container icon and then selecting the "WebUI" button. Using your new admin credentials you can also now login into the dashboard. In the top right, click on the icon with the cogs.

Preparing the Panel

Creating a Location

First, we need to create a location. Pterodactyl is built to run multiple gaming servers from a single panel so they have made it easy to locate and deploy game servers to different locations. For this guide, we will just set up the location "Home" as most of you are running Unraid at your homes.

Simply select the "Locations" tab and then in the top right corner, click "Create New".

A small dialogue box will appear, type in your location and then click "Create".

Creating your Node

WARNING

Make sure at this step that you are using the panel via your subdomain (panel.domain.com) or you will have issues down the line. Accessing via local IP will result in a cross domain error (CORS).

We now need to prepare for the daemon container. To do that we will add all the settings required to connect to the daemon container. First, click on the "Nodes" tab in the sidebar and then click "Create New".

A new window will appear where you will need to fill in the settings as per the screenshot below but choose your own RAM and Disc space that you would like to allocate for the gaming server.

Name the node.
Choose the location we set earlier.
This will be the subdomain we set up for the node server.
Since we are using an SSL connection with our subdomain, here we will be choosing "Use SSL Connection".
Again, since we are using a reverse proxy in front of the daemon container, here we will choose "Behind Proxy".
Here we need to point to the new share that we created for our gaming servers /mnt/user/pterodactyl-node/data
This is the total RAM memory we will allocate to the node for all of our gaming servers. Be sure to allocate enough RAM for the amount of gaming servers you would like to set up. (This depends on the type of games you would like to run). For this example we will assign 16GB of RAM (16384 - ignore the comma in the screenshot).
Here we can allow over allocation. If for some reason you are creating a gaming server and have already used up all your allocated RAM then this will allow you to use slightly more. For this example we will set it to 0 so that we can not use over the allocated amount.
This is where we will set the allowed disc space to be used for storing game server files. Here we will allocate the node 100GB of disk storage.
This allows over allocation of disk storage if for some reason you would need it, we will again set this to 0 so that we only used the allocated storage we set.
Since we are having the node behind a reverse proxy we need to set this port to the HTTPS port of 443.
Click create node.

Once you click "Create Node" at the bottom of your page it should take you to the Allocation tab. This is where you will allocate the server IP and ports available to be used by the gaming servers. For this example, we will add the Unraid server IP 192.168.60.20 and the port range of 25565-25583.

Click Submit. You have now successfully set up the allocations for the gaming server.

Now go to the configuration tab, showing you a Configuration File. Copy this text and paste it into something like Notepad++.

Below is an example of that configuration file:

Node config.yml

Now before we carry on, let's make some edits to this configuration file to suit our setup. We should only have to change the port it will be using from 443 to 8080 and also change the "remote:" scheme to from http tohttps.

Thanks to our discord user @xionous who realised that we also need to make sure the custom network Pterodactyl uses to create and control its gaming server containers is on a separate subnet to all our usual containers. By default Pterodactyl tries to create a network on 172.18.0.0/16 but for some users this network has already been used causing network overlapping errors. To do this we will add the following to the bottom of the config.yml:

docker:
  network:
    interface: 172.21.0.1
    name: pterodactyl_nw
    ispn: false
    driver: bridge
    network_mode: pterodactyl_nw
    is_internal: false
    enable_icc: true
    interfaces:
      v4:
        subnet: 172.21.0.0/16
        gateway: 172.21.0.1

For this example, we used 172.21.0.0/16 as this should be far away from any subnet you already have set up on your Unraid server. If you would like to choose your own you can run this command suggested by @xionous to list all your existing networks and their relevant subnets. You can then pick a subnet that is above this range.

for e in $(docker network ls --format '{{.Name}}') ; do docker network inspect $e --format '{{ printf "%-40s" .Name}} {{.IPAM.Config}}'; done

Here is an example of how the edited config.yml should look below:

debug: false
uuid: XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX
token_id: XXXXXXXXXXXXXX
token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
api:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: false
    cert: /etc/letsencrypt/live/node.domain.com/fullchain.pem
    key: /etc/letsencrypt/live/node.domain.com/privkey.pem
  upload_limit: 100
system:
  data: /mnt/user/pterodactyl-node/data
  sftp:
    bind_port: 2022
allowed_mounts: []
remote: https://panel.domain.com
docker:
  network:
    interface: 172.21.0.1
    name: pterodactyl_nw
    ispn: false
    driver: bridge
    network_mode: pterodactyl_nw
    is_internal: false
    enable_icc: true
    interfaces:
      v4:
        subnet: 172.21.0.0/16
        gateway: 172.21.0.1
allowed_origins:
- '*'

You can now copy and paste this into a file named config.yml in this folder /mnt/user/pterodactyl-node/config.yml

We can do this with the following command in the Unraid console:

nano /mnt/user/pterodactyl-node/config.yml

Then just right click in the terminal and click paste. To save this file and exit press ctrl + o, enter, ctrl + x

Swag Reverse Proxy

linuxserver.io has a reverse proxy that many unRAID users currently employ. Without some special configuration, it will be difficult to get connected to the node due to an Access Control Allow Origin add_header argument. SWAG also uses different .conf files to route the reverse proxy traffic so below is a list of all the changes that need to be made:

Ensure that the node is not proxied by Cloudflare. This method will not work if proxied by Cloudflare.
In your appdata/swag/nginx/site-confs/defaul.conf you will will find a few server blocks. They look like this: server { arguments } So we need to add the line add_header 'Access-Control-Allow-Origin' 'YOUR.DOMAIN'; to the arguments section. It can go into any server block, but you should put it down into one of the lower server blocks. Ensure you replace the YOUR DOMAIN text with your own domain. It should look like this:
```
server {
  add_header 'Access-Control-Allow-Origin' 'YOUR.DOMAIN';
{
```

In your appdata/swag/nginx/proxy-confs/ folder, create a new file named pterodactyl-node.conf. Open this file with your favorite text editor and copy and paste the below text. This is your template. Ensure the pterodactyl-node container is in the same docker network as SWAG and change the SUBDOMAIN and PORT number:

server { 
    listen 443 ssl; 
    listen [::]:443 ssl;
    server_name SUBDOMAIN.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        add_header 'Access-Control-Max-Age' 1728000;
        add_header 'Access-Control-Allow-Credentials' 'true';
        add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type';

    include /config/nginx/proxy.conf;
    include /config/nginx/resolver.conf;
    set $upstream_app pterodactyl-daemon;
    set $upstream_port CONTAINER PORT;
    set $upstream_proto http;
    proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }
}

And finally in your /pterodactyl-data/config.yml make sure you add the following at the bottom of the block.
```
allowed_origins:
- '*'
- PANELSUBDOMAIN.YOUR.DOMAIN
```

Now you're all done using your text editor. The final step is to go back into your panel and set your Daemon Port to 443.

Installing the Node container

We should now be ready to install the node container. Search the community apps again for Pterodactyl but this time we are going to choose the pterodactyl-deamon container.

Once you have clicked to install the daemon container you shouldn't have to do much apart from maybe add the container to your docker network and also change the port as we have done in the example below (because port 8080 is being used by another app). Once you have made any adjustments, click apply to deploy the container.

Checking the Node is Working

Now, a good way to check this is set up correctly once the container is running is to visit the node.domain.com in your favourite browser and you should get a reply, something like:

{"error":"The required authorization heads were not present in the request."}

Now that the container is up and running with all the subdomains set up, we should now be able to see back in the panel that the panel and node are connected successfully (the green heart icon next to the node).

Editing the config.yml

Once you start the node and it has picked up the config.yml file correctly and connected to the panel it will make some of it's own amendments. for it to work with our system how we need it to we will have to make a few final adjustments. If we use the same command we did before in the Unraid console we can start to edit the new config.yml.

nano /mnt/user/pterodactyl-node/config.yml

You can see that it has now automatically added a load of information. The few lines that we need to adjust are the file paths and possibly the time zone if this hasn't set itself correctly already.

We need to give it the correct path to the new share that we created:

system:
  root_directory: /mnt/user/pterodactyl-node/data
  log_directory: /var/log/pterodactyl
  data: /mnt/user/pterodactyl-node/data
  archive_directory: /mnt/user/pterodactyl-node/data/archives
  backup_directory: /mnt/user/pterodactyl-node/data/backups
  username: pterodactyl
  timezone: Europe/London

Adding a game server

Since we have already set up the panel ready to connect and also added the config file that the node needs to get running we should have the node connected to the panel.

We should now be able to start adding gaming servers to the panel. Click on the "Servers" tab in the sidebar and click "Create New".

Here you can name the game server that we are setting up, in this example, we are going to set up a Minecraft server so we are simply going to call it "Minecraft".
Here we are going to choose the node to install this on. We only have one set up so let's choose the node we just set up. For this example that will be "Home".
Here we can choose one of the ports that we set up previously in the node port allocation. For this example, we will use the Minecraft default port and also the first port available 25565

Here we can allocate the CPU resources. You can think of 100% as a whole core so if we allocate 400% we will be allocating a whole 4 cores. In this example we will allocate 2 cores worth of processing so 200%.
For memory allocation (RAM) we are going to give the gaming server lots of room with 8GB. This will very much depend on the gaming server you would like to run and what modification packs you choose to use etc.
The disc space allocation is how much storage out of the nodes allocated space is allowed for this single gaming server. In this example, 30GB should be enough.
Nest is the type of gaming server that we are going to set up. We can add many more "Nests" and "Eggs" to play almost any gaming server possible. To start with we will use the default that is set up and ready to go out of the box. Here we will be choosing Minecraft.
Next, we are going to choose the Egg. This is the type of Minecraft server that we would like to set up. For this example, we will be going with the "Paper" version.
This is where we can choose the base docker image to run the gaming server on. For the latest version of Minecraft, we need to also run the latest version of Java (Java 16). Click this drop-down menu and choose the Java 16 docker container.

PLEASE NOTE

Although it says setting the Memory limit to 0 will allow infinite resources, some game servers like Minecraft do not like this and will error out on the first boot. To prevent this it is good to add your required limit and increase it later if you find that is not enough.

Here is the gaming server start-up command. IF you do not know what you are doing it's best to leave this as default. You will notice as you choose different Nests and Eggs it will change this command for you.
Here you can choose the version of Minecraft you would like to run. For this example, we are going to run the latest (at the time of writing that is 1.17.1).
Here we can choose the gaming server file to run. For Minecraft it uses a file named server.jar. This should already be set so we can leave that as default.
Here we can choose the server build number. Since we are going to be running the latest and greatest we will also leave this as default.

Once you click to create a server you should get a success message notifying you that the server is currently being installed.

If we now click back on the "Servers" tab we should now see our new game server active in the list of servers.

Now before we can play on this Minecraft server we have to do the usual of agreeing to the EULA. But first we need to start the container to create this file. Head back to the homepage of Pterodactyl and you should see your new game server listed but not started. Lets click on the game server and then click the start button to create the Eula.txt file.

We should now see a load of text as it pulls down the latest container images needed to run this game server. This panel is clever enough to know that we need to accept the EULA so it deploys a dialogue box asking you to accept it.

Once you have accepted it the server will start to run! you have just started your first gaming server on pterodactyl.

Remote access to the gaming server

This process will be the same as our Minecraft Crafty guide so please follow this to expose your gaming server to the internet to allow your friends to play along with you.

Editing Game Server Files

Some games like Minecraft require some customization to get the server running just how you want it. Pterodactyl has made this process easier than ever. This can all be done within the gaming panel. While we are still on the game server we just set up let's click across to the "File Manager" tab.

Here we are able to add, remove and edit all files required to run a gaming server. This is especially useful for Minecraft servers for example to add and edit plugins to improve your gaming experience. For now, let's just update the "spawn-limit" for "monsters" from 70 to 90.

Now simply click save, go back to the server, and restart and you have your updated config applied to the server.

PLEASE NOTE

The way that Pterodactyl works is by creating docker containers on the host to run the gaming servers. When you log into the Unraid dashboard you will notice the stray servers with long container names. This is just how Pterodactyl works. To make it somewhat cleaner in the UI you can make a docker folder (see video here) and keep all your gaming servers contained in there. Below is an example of that.

Final Words

We hope you enjoyed this guide. It was conceptualized, written, and implemented by our Community Leader Hawks and it was all made possible thanks to aeleos who had done the original research to get it up and running on Unraid.