Easily Install Pelican Game Panel Using Docker

Published Nov 27, 2024

Updated Apr 7, 2025

Fast-track your Pelican setup by using the power of Docker and Nginx Proxy Manager!

Written by Andrew Flores

Pelican is the successor to Pterodactyl and is intended to improve on aspects of game server management where Pterodactyl fell short. Pelican is currently in Beta and this guide is currently up-to-date with Panel v1.0.0-beta19 and Wings v1.0.0-beta11.

The installation process for Pelican is quite intense and the networking configuration for the Panel and Wings and your actual game servers adds another layer of complexity. Docker is an excellent tool for wrapping up all the installation complexity into an image, and all you need to do is run the container with a couple environment variable tweaks.

The Pelican maintainers plan on using Docker as the preferred installation method once the project is out of Beta, and therefore have not published official images for the Panel or Wings. However, they have provided us with the tools to build the images (Dockerfile) and even examples for running the containers with Docker Compose.

If you’re interested, I made another post on easily setting up Pterodactyl in Docker, and this tutorial uses many of the same practices.

Before we get started, I’d like to give a shoutout to Jim’s Garage and TechnoTim for their excellent Pterodactyl tutorials that finally helped me get to a working configuration for Pterodactyl and Pelican.

Assumptions

In order to avoid excess verbosity, I am going to assume a couple things about your current experience and homelab setup.

1. Debian-based Linux distro (Ubuntu) with Docker installed
2. Familiarity with Docker and Docker Compose
3. Domain name
4. Nginx Proxy Manager installed on another machine and SSL certificate (wildcard or individual ones) for your domain configured within it. I will be covering NPM in this tutorial, but feel free to apply similar concepts to another reverse-proxy setup that you may have.

Getting Started

First, SSH into your server and clone down both the Panel and Wings repositories into your user’s home directory.

1
cd ~
2
git clone https://github.com/pelican-dev/panel.git
3
git clone https://github.com/pelican-dev/wings.git

Switch Git branches to the latest release to ensure stable features.

1
cd ~/panel
2
git switch release/v1.0.0-beta19
3

4
cd ~/wings
5
git switch release/v1.0.0-beta11

Edit ~/panel/Dockerfile to add the required ARG variables and make the changes that are suggested in one of the comments at the top of the file.

Declare and assign OS and Arch variables. See screenshot below for placement.

1
ARG TARGETOS=linux
2
ARG TARGETARCH=amd64

Uncomment the suggested lines.

1
FROM --platform=$TARGETOS/$TARGETARCH php:8.3-fpm-alpine as base
2

3
ADD --chmod=0755 https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/
4

5
RUN install-php-extensions bcmath gd intl zip opcache pcntl posix pdo_mysql
6

7
RUN rm /usr/local/bin/install-php-extensions

Replace both instances of localhost:5000/base-php:$TARGETARCH in the file with base. You will get an error while running docker build in a future step if you miss this.

1
# ================================
2
# Stage 1-1: Composer Install
3
# ================================
4

5
# Before
6
FROM --platform=$TARGETOS/$TARGETARCH localhost:5000/base-php:$TARGETARCH AS composer # BEFORE
7

8
# After
9
FROM --platform=$TARGETOS/$TARGETARCH base AS composer

1
# ================================
2
# Stage 5: Build Final Application Image
3
# ================================
4

5
# Before
6
FROM --platform=$TARGETOS/$TARGETARCH localhost:5000/base-php:$TARGETARCH AS final
7

8
# After
9
FROM --platform=$TARGETOS/$TARGETARCH base AS final

Next, build the Docker images for both repositories and tag them with a useful name. These image names must be reflected in the docker-compose.yml that we will create. Each build takes a few minutes to complete.

1
cd ~/panel
2
docker build -t pelican-dev/panel:latest .
3

4
cd ~/wings
5
docker build -t pelican-dev/wings:latest .
6

7
# Verify that images are present
8
docker images

Now that the images are built and stored locally, we can create a project directory where all relevant config and data files will live. I created one in my home directory /home/aflorzy/pelican. In that new folder, paste the below YAML into a file named docker-compose.yml. You will need to edit a few lines to personalize with your own information. See the comments in the collapsed sections for which variables may need tweaking. Everything else should work without modification.

1
services:
2
  panel:
3
    image: "pelican-dev/panel:latest"
19 collapsed lines
4
    container_name: pelican_panel
5
    restart: unless-stopped
6
    stdin_open: true
7
    tty: true
8
    ports:
9
      - "8080:80"
10
    volumes:
11
      - ./panel/data:/pelican-data
12
      - ./panel/logs:/var/www/html/storage/logs
13
      - ./Caddyfile:/etc/caddy/Caddyfile
14
    environment:
15
      TZ: America/Chicago # Replace with your time zone
16
      APP_TIMEZONE: America/Chicago # Replace with your time zone
17
      APP_ENV: production
18
      APP_URL: "https://pelican.local.aflorzy.com" # Replace with the FQDN you want to access the panel at
19
      ADMIN_EMAIL: andrewtflores@yahoo.com # Replace with your email
20
    networks:
21
      - pelican
22

23
  wings:
24
    image: "pelican-dev/wings:latest"
24 collapsed lines
25
    container_name: pelican_wings
26
    restart: unless-stopped
27
    ports:
28
      - "2022:2022"
29
      - "8443:443"
30
    stdin_open: true
31
    tty: true
32
    environment:
33
      TZ: America/Chicago # Replace with your time zone
34
      APP_TIMEZONE: America/Chicago # Replace with your time zone
35
      WINGS_UID: 1000
36
      WINGS_GID: 1000
37
      WINGS_USERNAME: pelican # Change if you want
38
    volumes:
39
      - "/var/run/docker.sock:/var/run/docker.sock"
40
      - "/var/lib/docker/containers/:/var/lib/docker/containers/"
41
      - "/etc/pelican/:/etc/pelican/"
42
      - "/var/lib/pelican/:/var/lib/pelican/"
43
      - "/var/log/pelican/:/var/log/pelican/"
44
      - "/tmp/pelican/:/tmp/pelican/"
45
      - "/etc/ssl/certs:/etc/ssl/certs:ro"
46
    networks:
47
      - wings1
48

49
networks:
50
  pelican:
51
    name: pelican
52
  wings1:
53
    name: wings1
6 collapsed lines
54
    driver: bridge
55
    ipam:
56
      config:
57
        - subnet: 172.50.0.0/16
58
    driver_opts:
59
      com.docker.network.bridge.name: wings1

Now we must create a Caddyfile that the Panel container will use internally for its networking. This is passed via a volume bind-mount in our docker-compose.yml file (already taken care of above). Paste the below YAML into a file named Caddyfile (capital “C”, no file extension) in your Pelican project directory.

1
{
2
    admin off
3
    email andrewtflores@yahoo.com
4
}
5

6
:80 {
7
    root * /var/www/html/public
8
    encode gzip
9

10
    php_fastcgi 127.0.0.1:9000
11
    file_server
12
}

It may seem unintuitive to add a Caddyfile, as it is typically used as a reverse-proxy solution parallel to NPM and Traefik. However, it allows the web server to be exposed from inside the Panel container, per suggestions from a user on the Pelican Discord

Setting up the Panel

You should now be able to start the Docker Compose stack! Run docker compose up -d and wait for the containers to finish starting. The panel container takes about a minute to complete its database initialization. You can monitor its status by running docker logs -f pelican_panel.

If you examine the Wings container logs now, you’ll notice that there is an error about a missing config.yml file. That is expected and we will be creating it in another step. For now, simply ignore it.

Now go to Nginx Proxy Manager and add a new Proxy Host with the FQDN you set in the Compose file and point it at the IP of your server with port 8080. I created a Proxy Host with the Domain Name pelican.local.aflorzy.com and used http Scheme, 192.168.1.33 Forward Hostname/IP, and 8080 Forward Port. I did not check any boxes on the Details tab, but selected my *.local.aflorzy.com certificate on the SSL tab and checked “Force SSL” and “HTTP/2 Support”.

Create a Proxy Host entry in NPM for wings1.local.aflorzy.com. Use http scheme, 192.168.1.33 Forward Hostname/IP, and 8443 Forward Port. Make sure to check “Websockets Support” so you can monitor the server logs in real-time after creating a server. Finally, select your wildcard certificate in the SSL tab and check “Force SSL” and “HTTP/2 Support”.

You should now be able to visit your Panel at https://<your-FQDN>/installer! Unlike Pterodactyl, Pelican has a short installation wizard to capture a few details about your installation upon the first visit. Note that you will be hit with a login screen instead of the installation wizard unless you append /installer to the end of your URL.

Fill out your relevant information here. App Name and App URL should already be filled out, but populate E-Mail, Username, and Password with your own information.

Accept the default Database selections.

Accept the default Cache selections.

Accept the default Queue selections.

Accept the default selections, and click “Finish”!

Setting up a Node (Wings)

Head to the Nodes tab and click “Create Node”.

Enter your Wings FQDN in the Domain Name field. Pelican will run a DNS lookup on this address to ensure it is registered as a valid DNS record. You can see that the DNS Record Check is marked as “Valid” for me and the IP address of my NPM instance is showing to the right. My NPM server IP shows here because that is where wings1.local.aflorzy.com is defined as a Proxy Host.

Now is a great time to add your Proxy Host entry in NPM if you haven’t already. That should solve an “Invalid” DNS Record Check on this page. I do this in the next step.

Create a Proxy Host entry in NPM for wings1.local.aflorzy.com. Use http scheme, 192.168.1.33 Forward Hostname/IP, and 8443 Forward Port. Make sure to check “Websockets Support” so you can monitor the server logs in real-time after creating a server. Finally, select your wildcard certificate in the SSL tab and check “Force SSL” and “HTTP/2 Support”.

Back in the Pelican UI, click “Next Step” on the Node creation screen and fill out the fields in the Advanced Settings tab. The only things I recommend changing are:

• Upload Limit: This could be helpful if you plan on uploading large files to your servers, such as an existing Minecraft world. I changed mine to 512MiB since I have mature Minecraft worlds whose data files have grown quite large.
• Memory: Set this to Limited and give some value that is smaller than the Memory allocated to your server/VM.
• Disk: Set this to Limited and give some value that is smaller than the Disk space allocated to your server/VM.
• CPU: Set this to Limited if you have other services besides Pelican/Wings running on your server.

Finally, click “Create Node”!

At this point, you will be presented with a pre-generated Configuration File for your Wings node. This is not automatically created as a file on your server, which is good because we have to make some modifications to it.

First, create a file on your server named config.yml in the directory /etc/pelican and paste the pre-generated YAML contents in it.

Next, copy the YAML below and paste it after the configuration code you just pasted.

IMPORTANT Make sure to DISABLE ssl by setting ssl.enabled: false

Keeping enabled: true will try to use the ssl.cert and ssl.key file paths that are referenced in that section. These do not exist since we are using certificates that were generated with LetsEncrypt inside of Nginx Proxy Manager. No certificate configuration is needed for this whole process except for adding individual certificates (pelican.domain.com, wings1.domain.com, minecraft.domain.com) or a wildcard certificate (*.domain.com) inside of NPM.

1
docker:
2
  network:
3
    interface: 172.50.0.1
4
    dns:
5
      - 192.168.1.1 # Replace with your default gateway if different
6
      - 1.0.0.1
7
    name: wings1
8
    ispn: false
9
    driver: bridge
10
    network_mode: wings1
11
    is_internal: false
12
    enable_icc: true
13
    network_mtu: 1500
14
    interfaces:
15
      v4:
16
        subnet: 172.50.0.0/16
17
        gateway: 172.50.0.1
18
      v6:
19
        subnet: fdba:17c8:6c94::/64
20
        gateway: fdba:17c8:6c94::1011
21
allowed_mounts: []
22
allowed_origins: []
23
allow_cors_private_network: false
24
ignore_panel_config_updates: false

The final contents of /etc/pelican/config.yml should look similar to the following:

1
debug: false
2
uuid: 6e6104e1-2022-4ed2-8dcc-2b45af4cfae5
3
token_id: xKdo7ktpJqY5w4RN
4
token: qh2zP4AsMy5whnS0TBAeZATJKrAyjUJkP8NtZwcKzZhAcgYPXnWej012TDzrkAs9
5
api:
6
  host: 0.0.0.0
7
  port: 443
8
  ssl:
9
    enabled: false
10
    cert: /etc/letsencrypt/live/wings1.local.aflorzy.com/fullchain.pem
11
    key: /etc/letsencrypt/live/wings1.local.aflorzy.com/privkey.pem
12
  upload_limit: 1000
13
system:
14
  data: /var/lib/pelican/volumes
15
  sftp:
16
    bind_port: 2022
17
allowed_mounts: []
18
remote: 'https://pelican.local.aflorzy.com'
19

20
docker:
21
  network:
22 collapsed lines
22
    interface: 172.50.0.1
23
    dns:
24
    - 192.168.1.1
25
    - 1.0.0.1
26
    name: wings1
27
    ispn: false
28
    driver: bridge
29
    network_mode: wings1
30
    is_internal: false
31
    enable_icc: true
32
    network_mtu: 1500
33
    interfaces:
34
      v4:
35
        subnet: 172.50.0.0/16
36
        gateway: 172.50.0.1
37
      v6:
38
        subnet: fdba:17c8:6c94::/64
39
        gateway: fdba:17c8:6c94::1011
40
allowed_mounts: []
41
allowed_origins: []
42
allow_cors_private_network: false
43
ignore_panel_config_updates: false

At this point, your Wings container should have a configuration file in the location that it needs. However, you will need to restart the container for it to recognize the new file.

1
docker compose down
2
docker compose up -d

I prefer to restart the whole Docker Compose stack.

Check the logs of your Wings container to make sure it picked up the config.yml file correctly and there are no errors. You should see output similar to that in the above screenshot.

Now return to the Pelican Panel web interface and navigate to the Nodes tab. You should see a green heart under the Health header! If you don’t, please check your node configuration before giving up or trying anything else. Also check to make sure you have a Proxy Hosts entry for wings1.domain.com in NPM and that it’s pointing at the correct IP address for your node. You will not be able to create any game servers until you see a green heart on this screen!

Setting up a Minecraft Server

Time to create a server! The first step for doing this is to create port allocations on your node. Navigate to the Nodes tab and click on your node. Scroll down to the Allocations section and click “Create Allocations”.

I recommend using IP address 0.0.0.0 as this IP is internal to the docker container. Assign an alias to the allocations if needed, and assign the port range 25560-25570 for Ports. Click “Submit” to save the allocations.

Now Navigate to the Servers tab and click “Create New”. I will be creating a Minecraft server in this case, but the process for other games should be similar.

Choose a server name like “Minecraft Latest”. Choose “wings1” in the Node dropdown. Select a port allocation that the server will run on. Click Next.

Select your game flavor in the Egg dropdown. I am choosing Vanilla Minecraft here. Optionally specify your desired version of Minecraft in the Server Version field. Leave the rest of the selections as default.

Set limits for Memory and Disk Space with the same considerations that were mentioned when allocating resources to the Node.

Finally, click “Create Server”. You will now see a screen where you can view the Server’s configuration and allocation. On the right-hand side, you’ll see the Server Status that should say “Installing” right away.

Click the “Console” button at the top to view the server management dashboard. Click “Start” to spin up the Minecraft server.

Connecting to the Server using a FQDN

In order to connect to your servers using a domain name, you need to configure a couple of things that regard Nginx Proxy Manager. First, if you are running NPM as a Docker container, you need to edit your compose stack or docker run command to expose the ports that your game servers will be running on. During the Node creation step, I allocated ports 25560-25570 for servers I might create. I now need to add the same port range inside of my NPM Docker Compose stack under ports.

1
ports:
2
  - 80:80
3
  - 81:81
4
  - 443:443
5
  - 25560-25570:25560-25570 # Game server port ranges

Next, you need to create a “Stream” in the NPM UI. Click the Hosts tab and select Streams in the list. Click “Add Stream” and fill in the information for one of the ports.

Note that you will have to manually add an entry for each port you want to create a Stream for. This can be pretty tedious if you have many entries to add. There is an open feature request with NPM on GitHub to solve this so it may become easier in the future.

Finally, decide which FQDN you want to access your servers at and create a DNS/CNAME record for it on your network using PiHole or AdGuard Home. I chose minecraft.local.aflorzy.com and pointed it at my NPM server’s IP.

It is possible to create a wildcard DNS matcher for your domain in PiHole or AdGuard Home so that all matching request are directed at your NPM instance. However, the downside of this is that the connection URL to Minecraft will not be limited to minecraft.local.aflorzy.com:25560. For example, I can connect to the same server using scoobydoo.local.aflorzy.com:25560. This can be fixed by creating a single DNS CNAME entry for each subdomain that NPM should handle.

Now it’s time to open up Minecraft and connect to your server! I am able to connect to my server at minecraft.local.aflorzy.com:25560.

Exposing Servers to the WAN

If you’ve gotten to this point, the only remaining step is to forward ports 80, 443, and 25560-25570 on your firewall and edit your DNS provider’s settings to point an A or CNAME record at your public IP address.

Final Thoughts

If you’ve made it to this point and are able to create and connect to servers, congratulations! If not, don’t get discouraged. The setup for Pelican and Pterodactyl is not nearly as straightforward as other Homelab services. We’ve all been there.

Take a closer look through this guide again, and keep searching around for other people’s guides. Consider joining the Pelican Discord server to see questions and solutions that other users have posted about. It is a thriving community so feel free to ask your own questions there.

Thank you for joining me in this journey of hosting Minecraft servers at home. The process has been long and arduous but is worth it in the end. Have a great day!