pterodactyl/documentation
1
0
Fork 0
mirror of https://github.com/pterodactyl/documentation.git synced 2025-12-10 21:05:59 -06:00
Code Issues Packages Projects Releases Wiki Activity

Include initial documentation for installing 0.8 & Wings

Browse Source
This commit is contained in:
Dane Everitt 2019-12-21 18:47:38 -08:00
parent 2ade858766
commit d74ac69dbb
No known key found for this signature in database
GPG Key ID: EEA66103B3D71F53
7 changed files with 573 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
.snippets/webservers/nginx-php7.3-nossl.conf Normal file
View File

@ -0,0 +1,44 @@
server {
listen 80;
server_name <domain>;
root /var/www/pterodactyl/public;
index index.html index.htm index.php;
charset utf-8;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt { access_log off; log_not_found off; }
access_log off;
error_log /var/log/nginx/pterodactyl.app-error.log error;
# allow larger file uploads and longer script runtimes
client_max_body_size 100m;
client_body_timeout 120s;
sendfile off;
location ~ \.php$ {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_pass unix:/run/php/php7.3-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param PHP_VALUE "upload_max_filesize = 100M \n post_max_size=100M";
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param HTTP_PROXY "";
fastcgi_intercept_errors off;
fastcgi_buffer_size 16k;
fastcgi_buffers 4 16k;
fastcgi_connect_timeout 300;
fastcgi_send_timeout 300;
fastcgi_read_timeout 300;
}
location ~ /\.ht {
deny all;
}
}

BIN
.vuepress/public/wings_configuration_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 570 KiB

226
panel/0.8/getting_started.md Normal file
View File

@ -0,0 +1,226 @@
# Getting Started
[[toc]]
Pterodactyl Panel is designed to run on your own web server. You will need to have root access to your server in order to run and use this panel.
You are expected to understand how to read documentation to use this Panel. We have spent many hours detailing how to install or upgrade our
software; take some time and read rather than copy and pasting and then complaining when things do not work. This panel does
not exist as a drag-and-drop service to run your servers. It is a highly complex system requiring multiple dependencies and
administrators willing to spend some time learning how to use it. **If you expect to be able to install this with no understanding
of basic linux system administration you should stop and turn around now.**
## Picking a Server OS
Pterodactyl runs on a wide range of operating systems, so pick whichever you are most comfortable using.
::: warning
Pterodactyl does not support most OpenVZ systems due to incompatabilities with Docker. If you are planning on running
this software on an OpenVZ based system you will &mdash; most likely &mdash; not be successful.
:::
| Operating System | Version | Supported | Notes |
| ---------------- | ------- | :-------: | ----- |
| **Ubuntu** | 14.04 | :warning: | Documentation assumes changes to `systemd` introduced in `16.04` |
| | 16.04 | :warning: | Ubuntu 16.04 is nearing end of life. |
| | 18.04 | :white_check_mark: | Documentation written assuming Ubuntu 18.04 as the base OS. |
| **CentOS** | 6 | :no_entry_sign: | Does not support all of the required packages. |
| | 7 | :white_check_mark: | Extra repos are required. |
| | 8 | :white_check_mark: | All required packages are part of the base repos. |
| **Debian** | 8 | :warning: | Debian 8 may need modifications to work with the latest docker and other requirements for the panel/daemon |
| | 9 | :white_check_mark: | Extra repos are required. |
| | 10 | :white_check_mark: | All required packages are part of the base repos. |
## Dependencies
* PHP `7.3` with the following extensions: `cli`, `openssl`, `gd`, `mysql`, `PDO`, `mbstring`, `tokenizer`, `bcmath`, `xml` or `dom`, `curl`, `zip`, and `fpm` if you are planning to use nginx
* MySQL `5.7` **or** MariaDB `10.1.3` or higher
* Redis (`redis-server`)
* A webserver (Apache, NGINX, Caddy, etc.)
* `curl`
* `tar`
* `unzip`
* `git`
* `composer`
### Example Dependency Installation
The commands below are simply an example of how you might install these dependencies. Please consult with your
operating system's package manager to determine the correct packages to install.
``` bash
# Add "add-apt-repository" command
apt -y install software-properties-common curl
# Add additional repositories for PHP, Redis, and MariaDB
LC_ALL=C.UTF-8 add-apt-repository -y ppa:ondrej/php
add-apt-repository -y ppa:chris-lea/redis-server
curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash
# Update repositories list
apt update
# Add universe repository if you are on Ubuntu 18.04
apt-add-repository universe
# Install Dependencies
apt -y install php7.3 php7.3-cli php7.3-gd php7.3-mysql php7.3-pdo php7.3-mbstring php7.3-tokenizer php7.3-bcmath php7.3-xml php7.3-fpm php7.3-curl php7.3-zip mariadb-server nginx tar unzip git redis-server
```
### Installing Composer
Composer is a dependency manager for PHP that allows us to ship everything you'll need code wise to operate the Panel. You'll
need composer installed before continuing in this process.
``` bash
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
```
## Download Files
The first step in this process is to create the folder where the panel will live and then move ourselves into that
newly created folder. Below is an example of how to perform this operation.
``` bash
mkdir -p /var/www/pterodactyl
cd /var/www/pterodactyl
```
Once you have created a new directory for the Panel and moved into it you'll need to download the Panel files. This
is as simple as using `curl` to download our pre-packaged content. Once it is downloaded you'll need to unpack the archive
and then set the correct permissions on the `storage/` and `bootstrap/cache/` directories. These directories
allow us to store files as well as keep a speedy cache available to reduce load times.
``` bash
curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/download/v0.8.0-alpha.1/panel.tar.gz
tar --strip-components=1 -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/
```
## Installation
Now that all of the files have been downloaded we need to configure some core aspects of the Panel.
::: tip Database Configuration
You will need a database setup and a user with the correct permissions created for that database before
continuing any further. If you are unsure how to do this, please have a look at [Setting up MySQL](/tutorials/mysql_setup.html).
:::
First we will copy over our default environment settings file, install core dependencies, and then generate a
new application encryption key.
``` bash
cp .env.example .env
composer install --no-dev --optimize-autoloader
# Only run the command below if you are installing this Panel for
# the first time and do not have any Pterodactyl Panel data in the database.
php artisan key:generate --force
```
::: danger
Back up your encryption key (APP_KEY in the `.env` file). It is used as an encryption key for all data that needs to be stored securely (e.g. api keys).
Store it somewhere safe - not just on your server. If you lose it, all encrypted data is useless and can't be restored, even if you have database backups.
:::
### Environment Configuration
Pterodactyl's core environment is easily configured using a few different CLI commands built into the app. This step
will cover setting up things such as sessions, caching, database credentials, and email sending.
``` bash
php artisan p:environment:setup
php artisan p:environment:database
# To use PHP's internal mail sending (not recommended), select "mail". To use a
# custom SMTP server, select "smtp".
php artisan p:environment:mail
```
### Database Setup
Now we need to setup all of the base data for the Panel in the database you created earlier. **The command below
may take some time to run depending on your machine. Please _DO NOT_ exit the process until it is completed!** This
command will setup the database tables and then add all of the Nests & Eggs that power Pterodactyl.
``` bash
php artisan migrate --seed
```
### Add The First User
You'll then need to create an administrative user so that you can log into the panel. To do so, run the command below.
At this time passwords **must** meet the following requirements: 8 characters, mixed case, at least one number.
``` bash
php artisan p:user:make
```
### Set Permissions
The last step in the installation process is to set the correct permissions on the Panel files so that the webserver can
use them correctly.
``` bash
# If using NGINX or Apache (not on CentOS):
chown -R www-data:www-data *
# If using NGINX on CentOS:
chown -R nginx:nginx *
# If using Apache on CentOS
chown -R apache:apache *
```
## Queue Listeners
We make use of queues to make the application faster and handle sending emails and other actions in the background.
You will need to setup the queue worker for these actions to be processed.
### Crontab Configuration
The first thing we need to do is create a new cronjob that runs every minute to process specific Pterodactyl tasks, such
as session cleanup and sending scheduled tasks to daemons. You'll want to open your crontab using `sudo crontab -e` and
then paste the line below.
```bash
* * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1
```
### Create Queue Worker
Next you need to create a new systemd worker to keep our queue process running in the background. This queue is responsible
for sending emails and handling many other background tasks for Pterodactyl.
::: warning
If you are using Ubuntu 14.04 you cannot use this method to run your queue worker. Please see these instructions for
installing Supervisor and setting up your queue. Ensure you use the same ExecStart line as below.
:::
Create a file called `pteroq.service` in `/etc/systemd/system` with the contents below.
``` text
# Pterodactyl Queue Worker File
# ----------------------------------
[Unit]
Description=Pterodactyl Queue Worker
After=redis-server.service
[Service]
# On some systems the user and group might be different.
# Some systems use `apache` or `nginx` as the user and group.
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3
[Install]
WantedBy=multi-user.target
```
::: tip Redis on CentOS
If you are using CentOS, you will need to replace `redis-server.service` with `redis.service` at the `After=` line in order to ensure `redis` starts before the queue worker.
:::
::: tip
If you are not using `redis` for anything you should remove the `After=` line, otherwise you will encounter errors
when the service starts.
:::
If you are are using redis for your system, you will want to make sure to enable that it will start on boot. You can do that by running the following command:
```bash
sudo systemctl enable --now redis-server
```
Finally, enable the service and set it to boot on machine start.
``` bash
sudo systemctl enable --now pteroq.service
```

69
panel/0.8/webserver_configuration.md Normal file
View File

@ -0,0 +1,69 @@
# Webserver Configuration
[[toc]]
::: danger
You should remove the default Apache or NGINX configuration as it will expose application secrets to malicious
users by default.
:::
## NGINX
You should paste the contents of the file below, replacing `<domain>` with your domain name being used in a file called
`pterodactyl.conf` and place it in `/etc/nginx/sites-available/`, or &mdash; if on CentOS, `/etc/nginx/conf.d/`.
### NGINX With SSL
This configuration assumes that you will be using SSL on both the Panel and Daemons for significantly improved communication
security between users and the Panel. You will need to get a valid SSL certificate which can be done for free by using
Let's Encrypt.
::: warning
When using the SSL configuration you MUST create SSL certificates, otherwise your NGINX will fail to start. See [Creating SSL Certificates](/tutorials/creating_ssl_certificates.html) documentation page for how to create these certificates before continuing.
:::
<<< @/.snippets/webservers/nginx-php7.3.conf{5,11,26-27}
Continue reading to the bottom of this section for the final steps with NGINX!
### NGINX Without SSL
<<< @/.snippets/webservers/nginx-php7.3-nossl.conf{3}
### Enabling Configuration
The final step is to enable your NGINX configuration and restart it.
``` bash
# You do not need to symlink this file if you are using CentOS.
sudo ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
# You need to restart nginx regardless of OS.
systemctl restart nginx
```
## Apache
You should paste the contents of the file below, replacing `<domain>` with your domain name being used in a file called
`pterodactyl.conf` and place it in `/etc/apache2/sites-available`, or &mdash; if on CentOS, `/etc/httpd/conf.d/`.
Note: When using Apache, make sure you have the `libapache2-mod-php` package installed or else PHP will not display on your webserver.
### Apache With SSL
Like the nginx configuration, this assumes you will be using SSL on both the Panel and Daemons for improved security.
::: warning
When using the SSL configuration you MUST create SSL certificates, otherwise your Apache will fail to start. See [Creating SSL Certificates](/tutorials/creating_ssl_certificates.html) documentation page for how to create these certificates before continuing.
:::
<<< @/.snippets/webservers/apache.conf{2,8,17-18}
### Apache Without SSL
<<< @/.snippets/webservers/apache-nossl.conf{2}
### Enabling Configuration
Once you've created the file above, simply run the commands below. If you are on CentOS _you do not need to run the commands
below!_ You only need to run `systemctl restart httpd`.
``` bash
# You do not need to run any of these commands on CentOS
sudo ln -s /etc/apache2/sites-available/pterodactyl.conf /etc/apache2/sites-enabled/pterodactyl.conf
sudo a2enmod rewrite
systemctl restart apache2
```

66
panel/upgrade/0.7_to_0.8.md Normal file
View File

@ -0,0 +1,66 @@
# Upgrading 0.7 to 0.8
::: danger Not for Production Use
**Pterodactyl 0.8 is currently unstable and missing significant features**. Do _not_ use this software
on a production system. Significant changes can still occur, and it has not been properly vetted by
the team for security and integrity.
:::
## Fetch Updated Files
The first step in the update process is to download the new panel files from Github. The command below will download
the release archive for the most recent version of Pterodactyl and save it in the current directory. Now is a good time
to ensure that you're in the `/var/www/pterodactyl` directory as the command below will automatically unpack in whatever
directory you are currently in.
``` bash
curl -L https://github.com/pterodactyl/panel/releases/download/v0.8.0-alpha.1/panel.tar.gz | tar --strip-components=1 -xzv
```
Once all of the files are downloaded we need to set the correct permissions on the cache and storage directories to avoid
any webserver related errors.
``` bash
chmod -R 755 storage/* bootstrap/cache
```
## Clear Compiled Assets
You'll need to clear the template cache to ensure users get the most recent templates.
``` bash
php artisan view:clear
```
## Update Dependencies
After you've downloaded all of the new files you will need to upgrade the core components of the panel. To do this,
simply run the commands below and follow any prompts.
``` bash
composer install --no-dev --optimize-autoloader
```
## Database Updates
::: warning
Running `db:seed` below will overwrite any changes you made to core Pterodactyl Nests, Eggs, or Egg Variables! This is
unavoidable, and this seeder must be run. To avoid this in the future, please create custom nests, or create custom
eggs for game variations.
:::
``` bash
php artisan migrate --force
php artisan db:seed --force
```
## Set Permissions
The last step is to set the proper owner of the files to be the user that runs your webserver. In most cases this
is `www-data` but can vary from system to system &mdash; sometimes being `nginx`, `apache`, or even `nobody`.
``` bash
# If using NGINX or Apache (not on CentOS):
chown -R www-data:www-data *
# If using NGINX on CentOS:
chown -R nginx:nginx *
# If using Apache on CentOS
chown -R apache:apache *
```

2
panel/upgrading.md
View File

@ -26,4 +26,4 @@ php artisan queue:restart
* [0.6.X to 0.7.15](/panel/upgrade/0.6_to_0.7.md)
* [0.7.X series](/panel/upgrade/0.7.md) <Badge text="current" vertical="middle"/>
<!--* [0.7.X to 0.8.0](#) <Badge text="beta" type="warn" vertical="middle"/>-->
* [0.7.X to 0.8.0](/panel/upgrade/0.7_to_0.8.md) <Badge text="alpha" type="warn" vertical="middle"/>

167
wings/installing.md Normal file
View File

@ -0,0 +1,167 @@
# Installing Wings
Wings is the next generation control daemon from Pterodactyl. This daemon has been rebuilt from the
ground up using Go and lessons learned from our first Nodejs Daemon.
::: danger Not for Production Use
**Wings is not stable and should not be used in a production environment.** Features are subject
to change, important features are missing, and the team has not vetted the performance or
security of the software.
:::
This software _requires Pterodactyl 0.8_ in order to run.
## Supported Systems
| Operating System | Version | Supported | Notes |
| ---------------- | ------- | :-------: | ----- |
| **Ubuntu** | 14.04 | :no_entry_sign: | Does not support `systemd`. |
| | 16.04 | :white_check_mark: | |
| | 18.04 | :white_check_mark: | |
| **CentOS** | 6 | :no_entry_sign: | Does not support all of the required packages. |
| | 7 | :white_check_mark: | |
| **Debian** | 8 | :warning: | Requires [kernel modifications](/daemon/debian_8_docker.md) to run Docker. |
| | 9 | :white_check_mark: | |
| | 10 | :white_check_mark: | |
| **Alpine Linux** | 3.4+ | :warning: | Not officially supported, but reportedly works. |
| **RHEL** | 7 | :warning: | Not officially supported, should work. |
| **Fedora** | 28 | :warning: | Not officially supported, should work. |
| | 29 | :warning: | Not officially supported, should work. |
## System Requirements
In order to run the Daemon you will need a system capable of running Docker containers. Most VPS and almost all
dedicated servers should be capable of running Docker, but there are edge cases.
If your provider makes use of `Virtuozzo`, `OpenVZ` (or `OVZ`), or `LXC` then you will most likely be unable to
run the Daemon. If you are unsure what your host is using there are a couple of options. The easiest is to check
their website, or reach out to their support team.
If you want to take a different approach, try using `lscpu` and checking what the virtualization type listed is. An
example of this is shown below which shows my hypervisor running with full virtualization — this means it will
support Docker without issues. If you see `KVM` for the vendor, chances are you're fine as well.
``` bash
dane@daemon:~$ lscpu | grep 'vendor\|type'
Hypervisor vendor: VMware
Virtualization type: full
```
If that doesn't work for some reason, or you're still unsure, you can also run the command below and as long as it
doesn't report `Xen` or `LXC` you're probably okay to continue.
``` bash
dane@daemon:~$ sudo dmidecode -s system-manufacturer
VMware, Inc.
```
## Dependencies
* curl
* Docker
### Installing Docker
For a quick install of Docker CE, you can execute the command below:
``` bash
curl -sSL https://get.docker.com/ | CHANNEL=stable bash
```
If you would rather do a manual installation, please reference the official Docker documentation for how to install Docker CE on your server. Some quick links
are listed below for commonly supported systems.
* [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/#install-docker-ce)
* [CentOS](https://docs.docker.com/install/linux/docker-ce/centos/#install-docker-ce)
* [Debian](https://docs.docker.com/install/linux/docker-ce/debian/#install-docker-ce)
::: warning Check your Kernel
Please be aware that some hosts install a modified kernel that does not support important docker features. Please
check your kernel by running `uname -r`. If your kernel ends in `-xxxx-grs-ipv6-64` or `-xxxx-mod-std-ipv6-64` you're
probably using a non-supported kernel. Check our [Kernel Modifications](kernel_modifications.md) guide for details.
:::
#### Start Docker on Boot
If you are on an operating system with systemd (Ubuntu 16+, Debian 8+, CentOS 7+) run the command below to have Docker start when you boot your machine.
``` bash
systemctl enable docker
```
#### Enabling Swap
On most systems, docker will be unable to setup swap space, you can check if this is the case by running `docker info`.
If it outputs `WARNING: No swap limit support` near the bottom, this is the case. Enabling swap is completely optional,
but we recommended doing it if you will be hosting for others, and to prevent OOM errors.
To do so, open `/etc/default/grub` as a root user, and find the line starting with `GRUB_CMDLINE_LINUX_DEFAULT`. Make
sure the line includes `swapaccount=1`.
After doing that, simply run `sudo update-grub` followed by `sudo reboot` to restart the server and have swap enabled.
Below is an example of what the line should look like, _do not copy this line verbatium, it often has additional
OS specific parameters._
``` text
GRUB_CMDLINE_LINUX_DEFAULT="swapaccount=1"
```
## Installing Wings
The first step for installing the daemon is to make sure we have the required directory structure setup. To do so,
run the commands below.
``` bash
mkdir -p /srv/wings/data/servers /srv/daemon-data
cd /srv/wings
```
::: warning OVH/SYS Servers
If you are using a server provided by OVH or SoYouStart please be aware that your main drive space is probably allocated to
`/home`, and not `/` by default. Please consider using `/home/daemon-data` for server data. This can be easily
set when creating the node.
:::
The next step is to download the software and unpack the archive.
``` bash
curl -L https://github.com/pterodactyl/wings/releases/download/v1.0.0-alpha.1/wings.tar.gz | tar --strip-components=1 -xzv
```
## Configure Daemon
Once you have installed the daemon and required components, the next step is to create a node on your installed Panel
Once you have done that there will be a tab called Configuration when you view the node.
Simply copy and paste the code block and paste it into a file called `config.yml` in `/srv/wings` and save it.
![](./../.vuepress/public/wings_configuration_example.png)
### Starting Wings
To start your daemon simply move into the daemon directory and run the command below which will start the daemon in
foreground mode. Once you are done, use `CTRL+C` to terminate the process. Depending on your server's internet connection
pulling and starting the Daemon for the first time may take a few minutes.
``` bash
sudo ./wings
```
You may optionally add the `-debug` flag to run Wings in debug mode.
### Daemonizing (using systemd)
Running Pterodactyl Daemon in the background is a simple task, just make sure that it runs without errors before doing
this. Place the contents below in a file called `wings.service` in the `/etc/systemd/system` directory.
``` text
[Unit]
Description=Pterodactyl Wings Daemon
After=docker.service
[Service]
User=root
WorkingDirectory=/srv/wings
LimitNOFILE=4096
PIDFile=/var/run/wings/daemon.pid
ExecStart=./wings
Restart=on-failure
StartLimitInterval=600
[Install]
WantedBy=multi-user.target
```
Then, run the commands below to reload systemd and start the daemon.
``` bash
systemctl enable --now wings
```