diff --git a/.vuepress/config.js b/.vuepress/config.js index 7c88050d..a5575078 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -69,10 +69,25 @@ module.exports = { ] }, { - title: 'Minecraft', + title: 'Creating Eggs', collapsable: false, children: [ - '/community/minecraft/networks.md', + '/community/config/eggs/creating_a_custom_egg.md', + '/community/config/eggs/creating_a_custom_image.md', + ], + }, + { + title: 'Node Configuration', + collapsable: false, + children: [ + '/community/config/nodes/add_node.md', + ], + }, + { + title: 'Game Configuration', + collapsable: false, + children: [ + '/community/games/minecraft.md', ], }, ], diff --git a/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg.png b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg.png new file mode 100644 index 00000000..19bf34ca Binary files /dev/null and b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg.png differ diff --git a/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Copy_Settings_From.png b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Copy_Settings_From.png new file mode 100644 index 00000000..f826e1ac Binary files /dev/null and b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Copy_Settings_From.png differ diff --git a/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Process_Management.png b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Process_Management.png new file mode 100644 index 00000000..5245eea3 Binary files /dev/null and b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Process_Management.png differ diff --git a/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Select.png b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Select.png new file mode 100644 index 00000000..2f21e729 Binary files /dev/null and b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Select.png differ diff --git a/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Startup.png b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Startup.png new file mode 100644 index 00000000..2708faeb Binary files /dev/null and b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Startup.png differ diff --git a/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Variables.png b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Variables.png new file mode 100644 index 00000000..dd35b8d0 Binary files /dev/null and b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Variables.png differ diff --git a/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Nest.png b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Nest.png new file mode 100644 index 00000000..bc50427a Binary files /dev/null and b/.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Nest.png differ diff --git a/.vuepress/public/community/config/nodes/pterodactyl_add_node_config.png b/.vuepress/public/community/config/nodes/pterodactyl_add_node_config.png new file mode 100644 index 00000000..bb238ac4 Binary files /dev/null and b/.vuepress/public/community/config/nodes/pterodactyl_add_node_config.png differ diff --git a/.vuepress/public/community/config/nodes/pterodactyl_add_node_create_button.png b/.vuepress/public/community/config/nodes/pterodactyl_add_node_create_button.png new file mode 100644 index 00000000..6eed3297 Binary files /dev/null and b/.vuepress/public/community/config/nodes/pterodactyl_add_node_create_button.png differ diff --git a/.vuepress/public/community/config/nodes/pterodactyl_add_node_new_page.png b/.vuepress/public/community/config/nodes/pterodactyl_add_node_new_page.png new file mode 100644 index 00000000..a0fe162a Binary files /dev/null and b/.vuepress/public/community/config/nodes/pterodactyl_add_node_new_page.png differ diff --git a/.vuepress/public/community/config/nodes/pterodactyl_node_tab.png b/.vuepress/public/community/config/nodes/pterodactyl_node_tab.png new file mode 100644 index 00000000..90a5a7af Binary files /dev/null and b/.vuepress/public/community/config/nodes/pterodactyl_node_tab.png differ diff --git a/community/config/eggs/creating_a_custom_egg.md b/community/config/eggs/creating_a_custom_egg.md new file mode 100644 index 00000000..1516010b --- /dev/null +++ b/community/config/eggs/creating_a_custom_egg.md @@ -0,0 +1,203 @@ +# Creating a Custom Egg +::: warning +You should not edit existing services or options that ship with the Panel. Each upgrade we push can make minor +changes to these, and you'll lose any changes you've made. +::: + +[[toc]] + +The first thing you'll need to do is create a new service. In this case, the name and description speak for themselves +in this case. The `Folder Name` _must be a unique name_ not being used by any other service, and should only +contain letters, numbers, underscores, and dashes. This is the name of the folder where the daemon will be storing +the service options on the daemon. + +The default start command is also required, however it can be changed per-option. + +## Create New Option +After creating the service, in the bottom right of the page you should see a button titled `New Egg`, press it. + +![](../../../.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Select.png) + +You will be taken to a new service option page which is where most of the configuration happens. The first thing +you need to do is select your service that you created previously from the `Associated Nest` dropdown. + +![](../../../.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Process_Management.png) + +After that, enter an Option Name to describe it, in this case I am using `Widget`. You will also need to provide a +_valid_ docker image, as well as a start command to be assigned to servers under this service option (remember, this +can be tweaked per-server if needed). + +_Docker images must be specifically designed to work with Pterodactyl Panel._ You should read more about that in +our [Creating a Docker Image](/community/config/eggs/creating_a_custom_image.md) guide. + +## Configure Process Management +This is perhaps the most important step in this service option configuration, as this tells the Daemon how to run everything. + +![](../../../.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Process_Management.png) + +The first field you'll encounter is `Copy Settings From`. The default selection is `None`. That is expected, and okay. +This dropdown is discussed at the end of this article. + +### Stop Command +Next, you'll encounter `Stop Command` and, as the name implies, this should be the command used to safely stop the +option. For some games, this is `stop` or `end`. Certain programs and games don't have a specified stop command, so +you can enter `^C` to have the daemon execute a `SIGINT` to end the process. + +### Log Storage +Logs are competely handeled by the daemon now and use the docker logs to output the complete output from the server. +This can be set like below. + +```json +{} +``` + +### Configuration Files +The next block is one of the most complex blocks, the `Configuration Files` descriptor. The Daemon will process this +block prior to booting the server to ensure all of the required settings are defined and set correctly. + +```json +{ + "server.properties": { + "parser": "properties", + "find": { + "server-ip": "0.0.0.0", + "enable-query": "true", + "server-port": "{{server.build.default.port}}", + "query.port": "{{server.build.default.port}}" + } + } +} +``` + +In this example, we are telling the Daemon to read `server.properties` in `/home/container`. Within this block, we +define a `parser`, in this case `properties` but the following are [valid parsers](https://github.com/Pterodactyl/Daemon/blob/develop/src/helpers/fileparser.js): + +* `file` — This parser goes based on matching the beginning of lines, and not a specific property like the other four. +Avoid using this parser if possible. +* `yaml` (supports `*` notation) +* `properties` +* `ini` +* `json` (supports `*` notation) +* `xml` + +Once you have defined a parser, we then define a `find` block which tells the Daemon what specific elements to find +and replace. In this example, we have provided four separate items within the `server.properties` file that we want to +find and replace to the assigned values. You can use either an exact value, or define a specific server setting from +the `server.json` file. In this case, we're assigning the default server port to be used as the `server-port` and +`query.port`. **These placeholders are case sensitive, and should have no spaces in them.** + +You can have multiple files listed here, the Daemon will process them in parallel before starting the server. When +using `yaml` or `json` you can use more advanced searching for elements. + +```json +{ + "config.yml": { + "parser": "yaml", + "find": { + "listeners[0].query_enabled": true, + "listeners[0].query_port": "{{server.build.default.port}}", + "listeners[0].host": "0.0.0.0:{{server.build.default.port}}", + "servers.*.address": { + "127.0.0.1": "{{config.docker.interface}}", + "localhost": "{{config.docker.interface}}" + } + } + } +} +``` + +In this example, we are parsing `config.yml` using the `yaml` parser. The first three find items are simply assigning +ports and IPs for the first listener block. The last one, `servers.*.address` uses wildcard matching to match any items +within the `servers` block, and then finding each `address` block for those items. + +::: v-pre +An advanced feature of this file configuration is the ability to define multiple find and replace statements for a +single matching line. In this case, we are looking for either `127.0.0.1` or `localhost` and replacing them with the +docker interface defined in the configuration file using `{{config.docker.interface}}`. +::: + +### Start Configuration +The last block to configure is the `Start Configuration` for servers running using this service option. + +```json +{ + "done": ")! For help, type ", + "userInteraction": [ + "Go to eula.txt for more info." + ] +} +``` + +In the example block above, we define `done` as the entire line, or part of a line that indicates a server is done +starting, and is ready for players to join. When the Daemon sees this output, it will mark the server as `ON` rather +than `STARTING`. We can also define `userInteraction` as an array of lines that should indicate that the server +*did not crash*, but rather stopped because the user needs to perform some action. + +In this case, we define it as the line asking users to agree to the EULA. You are not required to have +`userInteraction` lines, however if you are going to leave it empty, it should still be defined with an empty array, +as shown below: + +```json +{ + "done": ")! For help, type ", + "userInteraction": [] +} +``` + +That concludes basic service option configuration. + +## Copy Settings From +As mentioned above, there is a unique `Copy Settings From` dropdown when adding a new option. This gives you the +ability to, as the name suggests, copy settings defined above from a different option. + +![](../../../.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Copy_Settings_From.png) + +In the panel, we use this to copy settings that remain the same between similar service options, such as many of the +Minecraft options. + +For example, lets look at the `Sponge (SpongeVanilla)` service option. + +As you can see, it as been told to copy settings from `Vanilla Minecraft`. This means that any of the fields that are +left blank will inherit from the assigned parent. We then define a specific `userInteraction` line that is different in +Sponge compared to Vanilla, but tell it that everything else should remain the same. + +*Please note that `Copy Settings From` does not support nested copies, you can only copy from a single parent, +and that parent **must not be copying from another option.*** + +## Egg Variables +One of the great parts of the Egg Variables is the ability to define specific variables that users and/or admins can +control to tweak different settings without letting users modify the startup command. To create new variables, or edit +existing ones, visit the new service option you created, and click the `Variables` tab at the top of the page. Lets take +a look at an example variable that we can create. + +![](../../../.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Variables.png) + +::: v-pre +The name and description are rather self-explanitory, so I'll skip down to the `Environment Variable` box. This should +be an Alpha-Numeric name with underscores, and should be uppercase. This will be the name of the environment variable +which can be accessed in the startup command as `{{WOOZLE_WOO}}`, within file modifications as `{{env.WOOZLE_WOO}}`, or +just `${WOOZLE_WOO}` in any shell scripts (it is passed through in the environment). We also define a default value for +this environment variable in this example, but it is not required to do so. +::: + +The next section is `Permissions`, which is a dropdown with two options: `Users Can View` and `Users Can Edit`. + +* `Users Can View` — allows a user to view the field on the front-end, as well as the assigned value of that variable. +They will be able to see it replaced in their startup command. +* `Users Can Edit` — allows a user to edit the value of the variable, for example the name of their `server.jar` file +if running Minecraft. + +You should use caution here, even if you assign neither of the permissions it does not mean that the value will be +hidden. Crafty users will still be able to get the environment on their server. In most cases this is simply hiding +it from the user, and then used within the Dockerfile to perform actions, thus it is not important for the user to see. + +Finally, you will need to define some input rules to validate the value against. In this example, we use +`required|string|between:1,10`, which means the field is `required`, must be a `string`, and must be between `1` and +`10` characters in length. You can find [all of the available validation rules](https://laravel.com/docs/5.6/validation#available-validation-rules) +on the Laravel website. You can also use ReGEX based validation by using the `regex:` rule flag. For example, +[`required|regex:/^([\w\d._-]+)(\.jar)$/`](https://regex101.com/r/k4oEOn/1) will require the field, and will match the +regex as any letters or numbers (`\w\d`) including underscore (`_`), periods (`.`), and dashes (`-`) ending in `.jar`. + +They will then be visible when managing the startup for a server in both the Admin CP and on the Front-End. + +![](../../../.vuepress/public/community/config/eggs/Pterodactyl_Create_New_Egg_Startup.png) diff --git a/community/config/eggs/creating_a_custom_image.md b/community/config/eggs/creating_a_custom_image.md new file mode 100644 index 00000000..d890c870 --- /dev/null +++ b/community/config/eggs/creating_a_custom_image.md @@ -0,0 +1,147 @@ +# Creating a Custom Docker Image + +[[toc]] + +::: warning +This tutorial uses examples from our [`core:java`](https://github.com/pterodactyl/images/tree/java) docker image, +which can be found on Github. This tutorial also assumes some knowledge of [Docker](https://docker.io/), we suggest +reading up if this all looks foreign to you. +::: + +## Creating the Dockerfile +The most important part of this process is to create the [`Dockerfile`](https://docs.docker.com/engine/reference/builder/) +that will be used by the Daemon. Due to heavy restrictions on server containers, you must setup this file in a specific manner. + +We try to make use of [Alpine Linux](https://alpinelinux.org) as much as possible for our images in order to keep their size down. + +```bash +# ---------------------------------- +# Pterodactyl Core Dockerfile +# Environment: Java +# Minimum Panel Version: 0.6.0 +# ---------------------------------- +FROM openjdk:8-jdk-alpine + +MAINTAINER Pterodactyl Software, + +RUN apk add --no-cache --update curl ca-certificates openssl git tar bash sqlite fontconfig \ + && adduser -D -h /home/container container + +USER container +ENV USER=container HOME=/home/container + +WORKDIR /home/container + +COPY ./entrypoint.sh /entrypoint.sh + +CMD ["/bin/bash", "/entrypoint.sh"] +``` + +Lets walk through the `Dockerfile` above. The first thing you'll notice is the [`FROM`](https://docs.docker.com/engine/reference/builder/#from) declaration. + +```bash +FROM openjdk:8-jdk-alpine +``` + +In this case, we are using [`fopenjdk:8-jdk-alpine`](https://github.com/docker-library/openjdk) which provides us with Java 8. + +## Installing Dependencies +The next thing we do is install the dependencies we will need using Alpine's package manager: `apk`. You'll notice some +specific flags that keep the container small, including `--no-cache`, as well as everything being contained in a +single [`RUN`](https://docs.docker.com/engine/reference/builder/#run) block. + + +## Creating a Container User +Within this `RUN` block, you'll notice the `useradd` command. + +```bash +adduser -D -h /home/container container +``` +

All Pterodactyl containers must have a user named `container`, and the user home **must** be `/home/container`.

+ +After we create that user, we then define the default container [`USER`](https://docs.docker.com/engine/reference/builder/#user) +as well as a few [`ENV`](https://docs.docker.com/engine/reference/builder/#env) settings to be applied to things running +within the container. + +## Work Directory & Entrypoint +One of the last things we do is define a [`WORKDIR`](https://docs.docker.com/engine/reference/builder/#workdir) which +is where everything else will be executed. The `WORKDIR` must be set the `/home/container`. + +Finally, we need to copy our [`ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) script into +the docker image root. This is done using [`COPY`](https://docs.docker.com/engine/reference/builder/#copy), after which +we define the command to be used when the container is started using [`CMD`](https://docs.docker.com/engine/reference/builder/#cmd). +The `CMD` line should always point to the `entrypoint.sh` file. + +```bash +COPY ./entrypoint.sh /entrypoint.sh +CMD ["/bin/bash", "/entrypoint.sh"] +``` + +## Entrypoint Script +In order to complete this `Dockerfile`, we will need an `entrypoint.sh` file which tells Docker how to run this +specific server type. + +These entrypoint files are actually fairly abstracted, and the Daemon will pass in the start command as an environment +variable before processing it and then executing the command. + +```bash +#!/bin/bash +cd /home/container + +# Output Current Java Version +java -version ## only really needed to show what version is being used. Should be changed for different applications + +# Replace Startup Variables +MODIFIED_STARTUP=`eval echo $(echo ${STARTUP} | sed -e 's/{{/${/g' -e 's/}}/}/g')` +echo ":/home/container$ ${MODIFIED_STARTUP}" + +# Run the Server +${MODIFIED_STARTUP} +``` + +The second command, `cd /home/container`, simply ensures we are in the correct directory when running the rest of the +commands. We then follow that up with `java -version` to output this information to end-users, but that is not necessary. + +## Modifying the Startup Command +The most significant part of this file is the `MODIFIED_STARTUP` environment variable. What we are doing in this case +is parsing the environment `STARTUP` that is passed into the container by the Daemon. In most cases, this variable +looks something like the example below: + +```bash +STARTUP="java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}" +``` + +::: v-pre +You'll notice some placeholders there, specifically `{{SERVER_MEMORY}}` and `{{SERVER_JARFILE}}`. These both refer to +other environment variables being passed in, and they look something like the example below. +::: + +```bash +SERVER_MEMORY=1024 +SERVER_JARFILE=server.jar +``` + +There are a host of different environment variables, and they change depending on the specific service option +configuration. However, that is not necessarily anything to worry about here. + +```bash +MODIFIED_STARTUP=`eval echo $(echo ${STARTUP} | sed -e 's/{{/${/g' -e 's/}}/}/g')` +``` + +::: v-pre +The command above simply evaluates the `STARTUP` environment variable, and then replaces anything surrounded in +curly braces `{{EXAMPLE}}` with a matching environment variable (such as `EXAMPLE`). Thus, our `STARTUP` command: +::: + +```bash +java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}} +``` + +Becomes: + +```bash +java -Xms128M -Xmx1024M -jar server.jar +``` + +## Run the Command +The last step is to run this modified startup command, which is done with the line `${MODIFIED_STARTUP}`. diff --git a/community/config/nodes/add_node.md b/community/config/nodes/add_node.md new file mode 100644 index 00000000..c42dfc9c --- /dev/null +++ b/community/config/nodes/add_node.md @@ -0,0 +1,58 @@ +# Creating a New Node + +[[toc]] + +## Location +Head to the admin panel and click the Nodes tab on the left sidebar. After that, click 'Create New' on the +top right side to open the page to add a node. + +![](../../../.vuepress/public/community/config/nodes/pterodactyl_add_node_create_button.png) + +## Information Required + +![](../../../.vuepress/public/community/config/nodes/pterodactyl_add_node_new_page.png) + +* **Name**: a quick identifiable name for the daemon +* **Description**: a long description that is used to help you identify the node. +* **Location**: the location you have the node in. These are configured in the 'Locations' section of the panel and one +must be created before a node can be created. These simply act as categories for Nodes and serve no other purpose at +this time. +* **FQDN**: the fully qualified domain name for the node — for example: `node.demon.pterodactyl.io` +* **Communicate over SSL**: if the panel is using SSL the Daemon is required to use SSL as well. +* **Behind Proxy**: if you have the daemon behind a proxy that terminates SSL connections before arriving at the daemon +then this option should be selected. If none of that sentence made sense, this doesn't effect you. +* **Server File Directory**: the location on the physical server where the daemon is to store the files the servers +generate. By default this is `/srv/daemon-data`. + +::: tip OVH Users +Some OVH users regularly have their `/home` folder be the largest filesystem. You may want to change to use +`/home/daemon-data` if you are on a default OVH box. +::: + +* **Total Memory**: the total amount of ram the Node should be able to allocate automatically. +* **Memory Overallocate**: the percentage of ram to over-allocate on a Node. For example, if you have set a 10G memory +limit, with a 20% overallocation the Panel will allocate up to 12G of memory on this node in total. +* **Total Disk Space**: the totaly amount of ram the Node should be able to allocate automatically. +* **Disk Overallocate**: works the same way as memory overallocation. + +::: danger +Don't forget to account for OS overhead and other software requirements on machines. +::: + +* **Daemon Port**: the port that the Daemon should listen on. +* **Daemon SFTP Port**: the port the daemon sftp-server or standalone SFTP server listen on. + +## Install the Daemon +At this point you'll need to have the daemon installed on your machine. Check out the [documentation](/daemon/installing.md) +for more information, or try one of the community guides for [CentOS](/community/installation-guides/daemon/centos7.md), +[Ubuntu](/community/installation-guides/daemon/ubuntu1804.md), or [Debian](/community/installation-guides/daemon/debian9.md). + +## Configuring the Node +Go to the Node Configuration page + +![](../../../.vuepress/public/community/config/nodes/pterodactyl_add_node_config.png) + +Copy and paste the config into the `core.json` folder. (Default location is `/srv/daemon/config/core.json`) + +### Auto-Deploy +This will generate a command to run on the node server to configure the daemon for you. (This needs to be run in the `/srv/daemon` folder) diff --git a/community/minecraft/networks.md b/community/games/minecraft.md similarity index 94% rename from community/minecraft/networks.md rename to community/games/minecraft.md index 3dc92cfe..350a85e2 100644 --- a/community/minecraft/networks.md +++ b/community/games/minecraft.md @@ -1,19 +1,21 @@ -# Server Networks -This guide was written for Bungeecord, but should work fine for Waterfall and Hexacord servers. +# Minecraft [[toc]] +## Network Configuration +This guide was written for Bungeecord, but should work fine for Waterfall and Hexacord servers. + :::warning For the setup described below, it is necessary that all servers are on the same node. ::: -## Setting up the Network +### Setting up the Network The ideal setup for this involves a separated internal network with only one access point — the BungeeCord server — which is an easy configuration with Pterodactyl. In order to create a Bungeecord network you'll first need to add an allocation to your Node that makes your Bungeecord server publicly accessible. This allocation should be for your public IP address and the default port you wish to use — generally `25565`. -## Adding Additional Servers +### Adding Additional Servers All other servers that are a part of the network should be created on local interfaces — meaning they are not publicly accessible. Create new allocations on the localhost IP address `127.0.0.1` with some ports for the servers to use. You can also enter a port range, e.g. `30000-30010` which will get you 11 ports. @@ -22,12 +24,12 @@ Now create new servers and be sure to use your internal allocations — `127.0.0 servers to your network you'll use `172.18.0.1:` — or `127.0.0.1` which will automatically be resolved to your Docker network interface IP — as the IP address in your configuration file. -## In Conclusion +### In Conclusion * Only the proxy server (Bungeecord/Hexacord/Waterfall) should be attached to your publically accessible IP address. * You should _not_ make any modifications to IPTables. * All of the servers behind the proxy are safe from direct _external_ connections, assuming you bind them to `127.0.0.1`. -## UFW Firewall +### UFW Firewall If you are using a `ufw` firewall, it might be necessary to allow access to specific host ports. The following command allows incoming requests to `172.18.0.1`, which is the IP of the actual host server within the docker network. Replace `` with any port you want to be accessible. In this case use the port you assigned to the minecraft