Update README.md
This commit is contained in:
Michael Nguyen
parent
bf2a1d5d8f
commit
aee13ef7ea
1 changed files with 94 additions and 38 deletions
132
README.md
132
README.md
|
|
@ -1,4 +1,5 @@
|
|||
# pterodactyl-panel-docker
|
||||
[](https://github.com/TehTotalPwnage/pterodactyl-panel-docker/releases)
|
||||
> Docker Compose configuration for the [Pterodactyl Panel](https://github.com/Pterodactyl/Panel).
|
||||
|
||||
Pterodactyl is an open-source control panel used for hosting numerous game-related
|
||||
|
|
@ -6,37 +7,42 @@ services, such as Minecraft and Teamspeak servers. Setting it up, however, takes
|
|||
quite a few steps according to the [documentation](https://docs.pterodactyl.io/docs).
|
||||
|
||||
This Docker Compose configuration is aimed at removing a majority of the steps so
|
||||
that the installation process is almost as simple as cloning this build script and
|
||||
that the installation process is *almost* as simple as cloning this build script and
|
||||
running `docker-compose up`.
|
||||
|
||||
There are other Docker Compose setups available, including the [one](https://github.com/parkervcp/pterodactyl-panel-Dockerfile)
|
||||
created by one of the project's primary developers, parkervcp. However, I opted
|
||||
to create my own for a few reasons:
|
||||
created by one of the project's primary developers, parkervcp. This differs from
|
||||
those setups in various ways for a couple of different reasons:
|
||||
|
||||
1. These setups detract from Docker's "one service per container" philosophy. While
|
||||
it might be impossible to completely narrow down such a complex setup to one container,
|
||||
there are services, such as PHP and Nginx, that can be separated.
|
||||
2. I wanted to add a few alternative services for use in the Panel, such as Nginx
|
||||
instead of caddy.
|
||||
1. This setup splits the HTTP and PHP services into two different containers. Doing
|
||||
so allows for separation of concerns (a central Docker principle) and easier management
|
||||
of containers and Dockerfiles.
|
||||
2. This setup uses Nginx instead of Caddy. Various [benchmarks](https://community.centminmod.com/threads/caddy-http-2-server-benchmarks.5170/#post-34367)
|
||||
[indicate](https://hackernoon.com/caddy-a-modern-web-server-vs-nginx-e9e4abc443e)
|
||||
that Nginx performs better than Caddy in handling requests. In addition to this,
|
||||
Nginx, while having a more complicated configuration file, doesn't enforce HTTPS,
|
||||
a feature of Caddy which only complicates the setup of the HTTP Docker container.
|
||||
|
||||
## Usage
|
||||
The instructions are fairly self explanatory: clone the repository and launch the
|
||||
stack.
|
||||
project. Instructions on how to launch the project are listed below. All commands
|
||||
should be run from the repository directory.
|
||||
|
||||
In your favorite text editor, open docker-compose.yml change the port that you want
|
||||
the panel binded to. See below for more details. Once that's done, build and start
|
||||
the project.
|
||||
```
|
||||
git clone https://github.com/TehTotalPwnage/pterodactyl-panel-docker mypanel
|
||||
cd mypanel
|
||||
docker-compose -p <project_name> pull
|
||||
docker-compose -p <project_name> build
|
||||
docker-compose -p <project_name> up
|
||||
```
|
||||
I'd recommend cloning the repository into a specific directory name unless you want
|
||||
all your containers to be named pterodactylpaneldocker_service_number.
|
||||
The panel is now online. If this is your first time booting the panel, you'll also
|
||||
need to run the install script, which will run all of the necessary configuration
|
||||
scripts and database migrations for you.
|
||||
```
|
||||
vim docker-compose.yml
|
||||
```
|
||||
In your favorite text editor, change the port that you want the panel binded to.
|
||||
There are other settings you may need to modify that are documented below.
|
||||
```
|
||||
docker-compose pull
|
||||
docker-compose build
|
||||
docker-compose up
|
||||
docker exec -it <project name>_php_1 install
|
||||
# Restart the panel to load changes. The install script will remind you to do so.
|
||||
docker restart <project name>_php_1
|
||||
```
|
||||
The panel should now be ready, and you can connect to it via localhost at the port
|
||||
you specified in the Docker Compose file.
|
||||
|
|
@ -47,22 +53,72 @@ ports:
|
|||
```
|
||||
<host port number>:80
|
||||
```
|
||||
For the Panel, there are different environment variables that you can configure:
|
||||
- `panel_url` - The FQDN that the Panel will be hosted on. Required. (https://mc.example.com)
|
||||
- `timezone` - The timezone that the Panel will be hosted on. A list is available at http://php.net/manual/en/timezones.php.
|
||||
- `email_driver` - The email driver for the Panel. Options are smtp, mail, mailgun, mandrill, or postmark.
|
||||
- `panel_email` - The email address the panel should use. Required for all drivers.
|
||||
- `email_name` - The display name emails sent should have. Required for all drivers.
|
||||
- `email_user` - A username for the email server. Required for smtp, mandrill, mailgun, and postmark.
|
||||
- `email_pass` - A password for the email server. Required for smtp.
|
||||
- `email_domain` - The domain the driver should connect to. Required for smtp and mailgun.
|
||||
- `email_port` - The port of the email server. Required for smtp.
|
||||
- `admin_email` - The email address for the admin user. Required.
|
||||
- `admin_first` - The first name for the admin user. Required.
|
||||
- `admin_last` - The last name for the admin user. Required.
|
||||
- `admin_pass` - The password for the admin user. Required.
|
||||
- `admin_username` - The username for the admin user. Required.
|
||||
Two scripts are provided in order to aid with installation and upgrades.
|
||||
```
|
||||
# Use these scripts with the following command:
|
||||
docker exec -it <project name>_php_1 <script name>
|
||||
- install: Runs all the installation scripts, including migrations and configuration.
|
||||
- upgrade: Runs all the steps needed to upgrade to the latest version of the panel.
|
||||
```
|
||||
Note that depending on how old your version of the panel is, the upgrade command
|
||||
may not work. Be sure to check the changelog for each release and make sure your
|
||||
version is not listed as not working.
|
||||
|
||||
### Upgrading
|
||||
**Always remember to back up your data before upgrades! While I do my best to keep
|
||||
this Docker Compose configuration stable, there is always the chance that something
|
||||
can go horribly wrong! See the next section on how to run backups.**
|
||||
|
||||
Upgrading the project is slightly more complex. See the second caveat for an explanation
|
||||
as to why.
|
||||
|
||||
To upgrade, take down the project and wipe out the panel volume as it interferes
|
||||
with the upgrade process.
|
||||
```
|
||||
docker-compose -p <project name> down
|
||||
docker volume rm <project name>_panel
|
||||
```
|
||||
Rebuild and restart the project.
|
||||
```
|
||||
docker-compose -p <project name> pull
|
||||
docker-compose -p <project name> build
|
||||
docker-compose -p <project name> up
|
||||
```
|
||||
Finally, run the upgrade script.
|
||||
```
|
||||
docker exec -it <project name>_php_1 upgrade
|
||||
# Restart the panel to load changes. The upgrade script will remind you to do so.
|
||||
docker restart <project name>_php_1
|
||||
```
|
||||
|
||||
### Backups
|
||||
The volumes that you will need to backup are `db` (database), `env` (configuration),
|
||||
and `storage` (stored eggs and other files). These commands only work when the project
|
||||
is up (a caveat of Docker).
|
||||
```
|
||||
# Use mysqldump to back up the database.
|
||||
docker exec -it <project name>_db_1 mysqldump -u pterodactyl -ppterodactyl pterodactyl > database.sql
|
||||
# You can copy the .env file from the mounted env volume.
|
||||
docker cp <project name>_php_1:/var/www/html/env/.env .env
|
||||
# You can copy the mounted storage volume.
|
||||
docker cp <project name>_php_1:/var/www/html/pterodactyl/storage storage
|
||||
```
|
||||
|
||||
## Caveats
|
||||
- Do not stop the Docker Compose stack on the first run until supervisor announces
|
||||
that the setup is complete! Errors may occur if you kill the process too early!
|
||||
- Due to the need for a .env file early on in the build process, it is impossible
|
||||
to automatically run an install script, which would depend on checking for the existence
|
||||
of a .env file. You will need to manually run the install and upgrade scripts as
|
||||
necessary. Their use has been covered in the previous section.
|
||||
- The panel volume is required to share data between the HTTP and PHP containers,
|
||||
but the existence of this volume interferes with upgrade files due to how Docker
|
||||
works. These containers are separated for reasons already outlined, but this does
|
||||
mean that this volume must manually be removed on each upgrade.
|
||||
- A symbolic link is used to maintain the state of the .env file rather than Docker
|
||||
configs because of issues with **Docker itself**. Configs exist, but because they
|
||||
are read-only filesystems, they cannot be modified in the container, making their
|
||||
maintenance much more complicated. They would also require the use of Docker Swarms
|
||||
and Docker Services.
|
||||
- This setup is for Docker Compose, **not** for Docker Swarm or Docker Service. These
|
||||
two Docker services take much more convoluted configuration, including the setup
|
||||
of a swarm and the use of a local image registry, which would only complicate this
|
||||
setup.
|
||||
|
|
|
|||
Reference in a new issue