A lengthy guide on setting up Pterodactyl on TrueNAS SCALE

pterodactyl_truenas_scale.md

A guide to setup Pterodactyl on TrueNAS SCALE

I tried including everything I could think I had to do to get this up and running, I haven't got any database hosts running yet so this guide only contains what I have currently.

• Version: TrueNAS-SCALE-24.10-RC.2
• Created: 26/11/2023
• Last updated: 08/10/2024

Prerequisites

• Network interface is setup with a bridge configuration
• Reverse proxy
• Wildcard SSL Cert
• Domain name

Setup subdomains

Field	Value
Domain	play.<domain name>
Record Type	A
Destination	IP address

Field	Value
Domain	panel.<domain name>
Record Type	CNAME
Destination	Reverse proxy

Setup jailmaker

• https://github.com/Jip-Hop/jailmaker/tree/main

1. Create a dataset called jailmaker
2. Navigate to the TrueNAS Scale shell
3. Login as root sudo su
4. Navigate to jailmaker dataset location cd /mnt/<pool>/jailmaker
5. Install curl apt-get install curl
6. Download jailmaker curl --location --remote-name https://raw.githubusercontent.com/Jip-Hop/jailmaker/main/jlmkr.py
7. Allow execution of jailmaker chmod +x jlmkr.py
8. (Optional) Add an alias

Create directory to hold SSL certs

1. Navigate to the TrueNAS Scale shell
2. Login as root sudo su
3. Create a certs directory in /mnt/<pool>/jailmaker
4. cd into certs directory
5. Place your fullchain.pem and privkey.pem of your cert in this directory

Setup pterodactyl jail

1. Create a dataset called pterodactyl-backups
2. Create a dataset called pterodactyl-servers
3. Navigate to the TrueNAS Scale shell
4. Login as root sudo su
5. Create jail jlmkr create ptero
6. When prompted with Do you wish to create a jail from a config template? enter Y
7. Paste in the docker template found here
8. Change --network-bridge value to the name of your network bridge interface
9. Specify volume shares in additional flags

--bind='/mnt/<pool>/jailmaker/certs:/certs'
--bind='/mnt/<pool>/pterodactyl-backups:/var/lib/pterodactyl/backups'
--bind='/mnt/<pool>/pterodactyl-servers:/var/lib/pterodactyl/volumes'

11. Change startup=0 to 1
12. Start the jail
13. Shell into the jail jlmkr shell ptero

Setup static IP address for jail

1. Shell into the jail jlmkr shell ptero
2. Navigate to /etc/systemd/network/ within the jail
3. Edit 80-container-host0.network
4. Ensure the [Network] section looks like this

[Network]
DHCP=false
Address=192.168.0.12/24
Gateway=192.168.0.1
LinkLocalAddressing=no
LLDP=yes
EmitLLDP=customer-bridge

5. Change Gateway to your gateway address
6. Change Address to a static address of your choice
7. Restart network systemctl restart systemd-networkd
8. Validate IP assignment systemctl status systemd-networkd
9. Use ifconfig or ip a to ensure the ip is assigned

Open the following ports

Make sure the above ports are open using the jails static ip, not the host machine!

• 2096 (wings api) (tcp)
• 2097 (panel) (tcp)
• 2098 (wings sftp) (tcp)
• Game server allocation range (26300-26320) (tcp/udp) (up to you)
• (All the ports above can be changed to what you want to use)

Install pterodactyl panel

• https://github.com/pterodactyl-installer/pterodactyl-installer

1. Shell into the jail jlmkr shell ptero
2. Install curl apt-get install curl
3. Run installer bash <(curl -s https://pterodactyl-installer.se)
4. Select [0] Install the panel
5. Follow the below layout for script inputs

Field	Value
Database name	<up to you>
Database username	<up to you>
Database password	<up to you>
Timezone	<up to you>
Pterodactyl email	<up to you>
Admin email	<up to you>
Admin username	<up to you>
Admin firstname	<up to you>
Admin lastname	<up to you>
Admin password	<up to you>
FQDN	ptero.<domain name>
UFW	N
Lets Encrypt	N
Assume SSL	Y
Agree to HTTP request	Y
Proceed anyways	Y
Inital config completed, continue	Y
Enable sending anon telemetry	no

6. Installation completed
7. (optional) Get nano apt-get install nano
8. Edit panel nginx conf nano /etc/nginx/sites-enabled/pterodactyl.conf
9. Comment out or remove the server block containing port 80
10. Change the following below in the remaining server block

Old	New
listen 443 ssl http2;	listen 2097;
listen [::]:443 ssl http2;	listen [::]:2097;

11. Set ssl_certificate to /certs/fullchain.pem
12. Set ssl_certificate_key to /certs/privkey.pem
13. Restart nginx systemctl restart nginx
14. Ensure everything is ok systemctl status nginx

Setup panel proxy host

1. In your reverse proxy forward https://panel.<domain name> to your chosen static address with port 2097
2. Panel should be available to access on https://panel.<domain name>

Setup wings

• https://github.com/pterodactyl-installer/pterodactyl-installer

1. Shell into the jail jlmkr shell ptero
2. Run installer bash <(curl -s https://pterodactyl-installer.se)
3. Select [1] Install Wings
4. Follow the below layout for script inputs

Field	Value
UFW	N
Database hosts	N
Lets Encrypt	N
Proceed with installation	Y

5. Installation completed

Create a location

1. Login in to the panel https//panel.<domain name> with the admin credentials
2. Navigate to the Locations tab
3. Select Create New
4. Enter a <short code> and a <description>
5. Press Create

Create a node

1. Navigate to the Nodes tab
2. Select Create New
3. Enter the configs below

Field	Value
Name	master
Description	<The master node>
Location	<short code>
Node Visibility	Public
FQDN	play.<domain name>
Communicate Over SSL	Use SSL Connection
Behind Proxy	Not Behind Proxy
Daemon Port	2096
Daemon SFTP Port	2098

4. Enter your disk and memory limits
5. Select Create Node

Allocate Ports

1. Navigate to Nodes
2. Select the newly created node
3. Select Allocation tab
4. Under Assign New Allocations enter the following values below

Field	Value
IP Address
IP Alias	play.<domain name>
Ports	26300-26320

5. Press Submit

Configure wings

1. Navigate to Nodes
2. Select the newly created node
3. Select Configuration tab
4. Copy the configuration to clipboard
5. Go back to the shell
6. Navigate to /etc/pterodactyl
7. Create config nano config.yml
8. Paste clipboard config
9. Change the following values below

Field	Value
api.port	2096
system.sftp.port	2098
api.ssl.cert	/certs/fullchain.pem
api.ssl.key	/certs/privkey.pem

Fix panel -> wings routing issue

• if you know another way please let me know

1. Edit hosts nano /etc/hosts
2. Add new entry

127.0.0.1   play.<domain name>

• You should also do this on any system that runs on the same network and will access the panel (using the servers host ip) e.g.

192.168.xx.xx   play.<domain name>

Fix ipv6 docker container creation issue

1. Create a clone of the pterodactyl wings docker network bridge with ipv6 disabled

docker network create \
 -d bridge \
 --ipv6=false \
 -o "com.docker.network.bridge.enable_icc"="true" \
 -o "com.docker.network.bridge.enable_ip_masquerade"="true" \
 -o "com.docker.network.bridge.host_binding_ipv4"="0.0.0.0" \
 -o "com.docker.network.driver.mtu"="1500" \
 -o "com.docker.network.bridge.name"="pterodactyl0" \
 pterodactyl_nw

Start up wings

1. Enable wings service systemctl enable wings
2. Start wings service systemctl start wings
3. Check wings is running systemctl status wings
4. Checking the node on the panel should show the wings version

Testing

• Create a minecraft server
• Login to the panel and manage it locally
• Login through a vpn or through a different network
• Access the panel, try join the minecraft server

Setup panel settings

Mail

• Used for sending emails to users (invites, pass resets)

1. Open panel https://panel.<domain name>
2. Navigate to Settings
3. Select Mail tab
4. Enter smtp details (gmail can be used with app password)

reCAPTCHA

• Used for logging in and spam prevention

1. Open panel https://panel.<domain name>
2. Navigate to Settings
3. Select Advanced tab
4. Register an invisible reCAPTCHA
5. Copy in the site and secret keys
6. Press Save