OpenWebUI-RAG/software/pterodactyl-panel/pterodactyl-docs.md

```markdown
# Pterodactyl Knowledge Base

## Table of Contents
- [Introduction](#introduction)
- [About Pterodactyl](#about-pterodactyl)
- [Key Features](#key-features)
- [Installation Guides](#installation-guides)
  - [Panel Installation](#panel-installation)
  - [Wings Installation](#wings-installation)
  - [Webserver Configuration](#webserver-configuration)
- [Community Guides and Tutorials](#community-guides-and-tutorials)
  - [Creating a New Node](#creating-a-new-node)
  - [Creating a Custom Docker Image](#creating-a-custom-docker-image)
  - [Creating a Custom Egg](#creating-a-custom-egg)
- [Operating System Specific Installations](#operating-system-specific-installations)
  - [Enterprise Linux 8 and Fedora Server 40](#enterprise-linux-8-and-fedora-server-40)
  - [Debian 11, 12 & 13](#debian-11-12-13)
  - [CentOS 7](#centos-7)
- [Advanced Configurations](#advanced-configurations)
  - [Using Mounts](#using-mounts)
  - [Upgrading PHP](#upgrading-php)
- [Development and Customization](#development-and-customization)
  - [Building Wings](#building-wings)
  - [Building Panel Assets](#building-panel-assets)
- [Legacy Upgrades](#legacy-upgrades)
- [Kernel Modifications](#kernel-modifications)

## Introduction
Welcome to the Pterodactyl Knowledge Base. This document provides structured information on installing, configuring, and using Pterodactyl, a game server management panel.

## About Pterodactyl
**Pterodactyl®** is a free, open-source game server management panel built with PHP, React, and Go. It runs all game servers in isolated Docker containers for security, providing a user-friendly interface.

## Key Features
- **Security First**: Uses bcrypt hashing, AES-256-CBC encryption, and HTTPS support.
- **Modern Tooling**: Built on a modern stack with best design practices.
- **Docker to the Core**: Runs all servers in isolated Docker containers.
- **Free & Open Source**: Fully open source under a MIT license.
- **User Friendly**: Intuitive interface for easy management.
- **Scalable**: Suitable for hosting companies and personal use.

## Installation Guides

### Panel Installation
- **Current Version**: 1.11
- **Getting Started**: Includes webserver configuration, additional configuration, updating, and troubleshooting.

### Wings Installation
- **Current Version**: 1.11
- **Installation**: Instructions for installing, upgrading, and migrating to Wings.

### Webserver Configuration
- Prepare SSL certificates before configuring NGINX or Apache.
- Use Caddy for automatic SSL management if needed.
- Specific configurations provided for NGINX and Apache.

## Community Guides and Tutorials

### Creating a New Node
- **Location Information Required**: Name, description, location, FQDN, SSL communication, server directory, memory, and disk space allocations.
- **Installation**: Install the Daemon and configure the node.

### Creating a Custom Docker Image
- **Dockerfile Creation**: Use Alpine Linux, install dependencies, create a container user, and set the work directory and entrypoint.
- **Entrypoint Script**: Modify startup commands and run the server.

### Creating a Custom Egg
- **Service Creation**: Create new options, configure process management, stop commands, log storage, and configuration files.
- **Variables**: Define specific variables and permissions for users.

## Operating System Specific Installations

### Enterprise Linux 8 and Fedora Server 40
- **Dependencies**: Install Docker and configure firewall.
- **Wings Installation**: Follow official documentation.

### Debian 11, 12 & 13
- **Dependencies**: Install PHP, MariaDB, Redis, and other necessary packages.
- **Installation**: Follow official documentation for further steps.

### CentOS 7
- **Dependencies**: Install Docker, configure SELinux, and set up the firewall.
- **Panel Installation**: Follow official documentation for further steps.

## Advanced Configurations

### Using Mounts
- **Configuration**: Specify mountable directories in the Wings configuration.
- **Panel Setup**: Configure mounts in the admin panel for server use.

### Upgrading PHP
- **Version Requirements**: Reference table for PHP versions by panel version.
- **Installation**: Commands to add repositories and install PHP 8.3.

## Development and Customization

### Building Wings
- **Build Requirements**: Requires Go programming knowledge.
- **Process**: Compile Wings and install the binary.

### Building Panel Assets
- **Dependencies**: NodeJS and Yarn required.
- **Build Process**: Rebuild the Panel frontend using Yarn.

## Legacy Upgrades
- **Version Transition**: Guide for upgrading from 0.7.X to 1.3.x.
- **Maintenance Mode**: Enter maintenance mode before upgrading dependencies.

## Kernel Modifications
- **Update Process**: Install new kernels and update GRUB.
- **Verification**: Confirm kernel installation and set default boot.

For more detailed information and additional sections, please refer to the official Pterodactyl documentation and community guides.
```

```markdown
# Pterodactyl Knowledge Base

This structured knowledge base provides detailed instructions and information for installing, configuring, and troubleshooting Pterodactyl Panel and related components.

## Table of Contents

- [Installation](#installation)
  - [Download Files](#download-files)
  - [Installation Process](#installation-process)
  - [Environment Configuration](#environment-configuration)
  - [Queue Listeners](#queue-listeners)
- [Enterprise Linux 8 and Fedora Server 40](#enterprise-linux-8-and-fedora-server-40)
  - [Install Dependencies](#install-dependencies)
  - [PHP Configuration](#php-configuration)
- [Additional Configuration](#additional-configuration)
  - [Backups](#backups)
  - [Reverse Proxy Setup](#reverse-proxy-setup)
  - [reCAPTCHA](#recaptcha)
  - [Telemetry](#telemetry)
- [Updating the Panel](#updating-the-panel)
  - [Panel Version Requirements](#panel-version-requirements)
  - [Manual Upgrade](#manual-upgrade)
- [Standalone SFTP Server](#standalone-sftp-server)
- [Webserver Configuration](#webserver-configuration)
- [Community Standards](#community-standards)
- [Terminology](#terminology)
- [Migrating to Wings](#migrating-to-wings)
- [Troubleshooting](#troubleshooting)
- [About](#about)
  - [Core Project Team](#core-project-team)
  - [Sponsors](#sponsors)
  - [License](#license)
- [Creating SSL Certificates](#creating-ssl-certificates)

## Installation

### Download Files

1. **Create Directory**: Create a directory for the panel and navigate to it.
   ```bash
   mkdir -p /var/www/pterodactyl
   cd /var/www/pterodactyl
   ```

2. **Download Panel Files**: Use `curl` to download the panel files and set permissions.
   ```bash
   curl -Lo panel.tar.gz https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz
   tar -xzvf panel.tar.gz
   chmod -R 755 storage/* bootstrap/cache/
   ```

### Installation Process

1. **Database Setup**: Create a database and user with the necessary permissions.
   ```sql
   CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'yourPassword';
   CREATE DATABASE panel;
   GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1' WITH GRANT OPTION;
   ```

2. **Install Core Dependencies**: Copy environment settings and install dependencies.
   ```bash
   cp .env.example .env
   COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader
   ```

3. **Generate Encryption Key**: Generate a new encryption key.
   ```bash
   php artisan key:generate --force
   ```

4. **Environment Setup**: Configure sessions, caching, and email sending.
   ```bash
   php artisan p:environment:setup
   php artisan p:environment:database
   php artisan p:environment:mail
   ```

5. **Database Migration**: Set up the database tables.
   ```bash
   php artisan migrate --seed --force
   ```

6. **Create Admin User**: Create an administrative user.
   ```bash
   php artisan p:user:make
   ```

7. **Set File Permissions**: Set the correct permissions for the webserver.
   ```bash
   chown -R www-data:www-data /var/www/pterodactyl/*
   ```

### Queue Listeners

- **Crontab Configuration**: Add a cronjob for processing tasks.
  ```bash
  * * * * * php /var/www/pterodactyl/artisan schedule:run >> /dev/null 2>&1
  ```

- **Queue Worker**: Create a systemd worker for the queue process.

## Enterprise Linux 8 and Fedora Server 40

### Install Dependencies

1. **Update System**:
   ```bash
   sudo dnf update -y
   ```

2. **Install Repositories**:
   ```bash
   sudo dnf install -y epel-release
   sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm
   ```

3. **Enable PHP 8.3**:
   ```bash
   sudo dnf module reset php
   sudo dnf module enable php:remi-8.3 -y
   ```

4. **Install Dependencies**:
   ```bash
   sudo dnf install -y php php-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip} mariadb mariadb-server nginx redis zip unzip tar
   ```

5. **Enable Services**:
   ```bash
   sudo systemctl enable --now mariadb nginx redis
   ```

6. **Firewall Configuration**:
   ```bash
   sudo firewall-cmd --add-service=http --permanent
   sudo firewall-cmd --add-service=https --permanent
   sudo firewall-cmd --reload
   ```

### PHP Configuration

- **Create PHP-FPM Configuration**:
  ```ini
  [pterodactyl]
  user = nginx
  group = nginx
  listen = /var/run/php-fpm/pterodactyl.sock
  listen.owner = nginx
  listen.group = nginx
  listen.mode = 0750
  pm = ondemand
  pm.max_children = 9
  pm.process_idle_timeout = 10s
  pm.max_requests = 200
  ```

- **Start PHP-FPM**:
  ```bash
  sudo systemctl enable --now php-fpm
  ```

## Additional Configuration

### Backups

- **Local Backups**: Set the backup driver in `.env`.
  ```env
  APP_BACKUP_DRIVER=wings
  ```

- **S3 Backups**: Configure S3 settings in `.env`.
  ```env
  APP_BACKUP_DRIVER=s3
  AWS_DEFAULT_REGION=
  AWS_ACCESS_KEY_ID=
  AWS_SECRET_ACCESS_KEY=
  AWS_BACKUPS_BUCKET=
  AWS_ENDPOINT=
  ```

### Reverse Proxy Setup

- **Modify `.env` for Proxies**:
  ```env
  TRUSTED_PROXIES=127.0.0.1
  ```

- **NGINX Configuration**:
  ```nginx
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
  ```

### reCAPTCHA

- **Configuring reCAPTCHA**: Generate and apply your own keys in the admin panel.

- **Disable reCAPTCHA**: Use the admin panel to disable reCAPTCHA if necessary.

### Telemetry

- **How It Works**: Telemetry collects anonymous usage data to help improve the software.

- **Enabling/Disabling Telemetry**:
  ```env
  PTERODACTYL_TELEMETRY_ENABLED=true
  ```

## Updating the Panel

### Panel Version Requirements

- Ensure your Wings version matches the Panel version. Supported PHP versions vary by Panel version.

### Manual Upgrade

1. **Enter Maintenance Mode**:
   ```bash
   php artisan down
   ```

2. **Download Update**:
   ```bash
   curl -L https://github.com/pterodactyl/panel/releases/latest/download/panel.tar.gz | tar -xzv
   ```

3. **Update Dependencies**:
   ```bash
   composer install --no-dev --optimize-autoloader
   ```

4. **Clear Cache**:
   ```bash
   php artisan view:clear
   php artisan config:clear
   ```

5. **Database Updates**:
   ```bash
   php artisan migrate --seed --force
   ```

6. **Set Permissions**:
   ```bash
   chown -R www-data:www-data /var/www/pterodactyl/*
   ```

7. **Restart Queue Workers**:
   ```bash
   php artisan queue:restart
   ```

8. **Exit Maintenance Mode**:
   ```bash
   php artisan up
   ```

## Standalone SFTP Server

- **Disable Daemon's SFTP**: Modify your Daemon's `core.json`.
  ```json
  "sftp": {
    "enabled": false
  }
  ```

- **Download and Start Standalone Server**:
  ```bash
  curl -Lo sftp-server https://github.com/pterodactyl/sftp-server/releases/download/v1.0.5/sftp-server
  chmod +x sftp-server
  ./sftp-server
  ```

## Webserver Configuration

- **Remove Default Configuration**: Remove default NGINX configuration.
  ```bash
  rm /etc/nginx/sites-enabled/default
  ```

- **Create NGINX Configuration File**: Replace `<domain>` with your domain.
  ```nginx
  server {
    listen 80;
    server_name <domain>;
    return 301 https://$server_name$request_uri;
  }
  ```

- **Enable Configuration**: Symlink and restart NGINX.
  ```bash
  sudo ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
  sudo systemctl restart nginx
  ```

## Community Standards

- **Be Mature**: Maintain maturity and respect in all interactions.

- **Limit Drama**: Avoid negative discussions about others.

- **Be Patient**: Understand that support is community-driven and voluntary.

- **Commercial Services**: Avoid discussing paid services unless noted.

## Terminology

- **Panel**: The Pterodactyl Panel itself.
- **Node**: A machine running an instance of Wings.
- **Wings**: Service interfacing with Docker and the Panel.
- **Server**: A running instance created by the panel.
- **Docker**: Platform for running containerized applications.
- **Nest/Egg**: Configuration for specific games or services.

## Migrating to Wings

1. **Install Wings**:
   ```bash
   mkdir -p /etc/pterodactyl
   curl -L -o /usr/local/bin/wings https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_amd64
   chmod u+x /usr/local/bin/wings
   ```

2. **Copy Configuration File**: Create `config.yml` in `/etc/pterodactyl`.

3. **Remove Old Daemon**:
   ```bash
   systemctl stop wings
   rm -rf /srv/daemon
   apt -y remove nodejs
   ```

4. **Daemonize Wings**: Update `wings.service` and start Wings.
   ```systemd
   [Unit]
   Description=Pterodactyl Wings Daemon
   After=docker.service

   [Service]
   User=root
   WorkingDirectory=/etc/pterodactyl
   ExecStart=/usr/local/bin/wings

   [Install]
   WantedBy=multi-user.target
   ```

## Troubleshooting

### Reading Error Logs

- **Retrieve Logs**:
  ```bash
  tail -n 100 /var/www/pterodactyl/storage/logs/laravel-$(date +%F).log
  ```

- **Understand Errors**: Focus on the human-readable exception line.

### Cannot Connect to Server Errors

- **Check Wings Status**:
  ```bash
  systemctl status wings
  ```

- **Browser Console Check**: Use developer tools to inspect errors.

### Invalid MAC Exception

- **Restore `APP_KEY`**: Ensure original `APP_KEY` is restored from `.env`.

### SELinux Issues

- **Allow Redis**:
  ```bash
  audit2allow -a -M redis_t
  semodule -i redis_t.pp
  ```

- **Allow HTTP Port**:
  ```bash
  audit2allow -a -M http_port_t
  semodule -i http_port_t.pp
  ```

## About

### Core Project Team

- **Dane Everitt**: Founder & Former Project Maintainer
- **Matthew Penner**: Project Maintainer
- **Stepan Fedotov**: WHMCS Module Maintainer
- **Michael Parker**: Egg Developer, Docker Integration

### Sponsors

- **Aussie Server Hosts**: High Performance Server Hosting
- **CodeNode LLC**: Affordable hosting with dedicated IPs
- **BisectHosting**: Reliable server hosting since 2012
- **MineStrator**: Highend French hosting company
- **HostEZ**: US & EU Hosting with DDoS Protection

### License

- **MIT License**: Code released under the MIT License.

## Creating SSL Certificates

1. **Install Certbot**:
   ```bash
   sudo apt update
   sudo apt install -y certbot python3-certbot-nginx
   ```

2. **Generate Certificate**:
   ```bash
   certbot certonly --nginx -d example.com
   ```

3. **Auto Renewal**:
   ```bash
   0 23 * * * certbot renew --quiet --deploy-hook "systemctl restart nginx"
   ```

4. **Troubleshooting**: Renew certificates and restart services if expired.
   ```bash
   certbot renew
   systemctl restart nginx
   ```
```

```markdown
# Knowledge Base

## Reconfiguring Caddy to Use Cloudflare DNS

### Steps to Create an API Token
1. Under **Zone Resources**, select your DNS zone.
2. Click "Continue to summary".
3. Review the API token summary and click "Create Token".
4. Copy the API token to the clipboard.

### Configuring Caddy
- Create an environment variable file (e.g., `.env`) at `/etc/caddy/.secrets.env`.
- Store the Cloudflare API token:
  ```env
  CLOUDFLARE_API_TOKEN=<your cloudflare api token>
  ```
- Set permissions to 0600 for security:
  ```bash
  chown caddy:caddy /etc/caddy/.secrets.env
  chmod 0600 /etc/caddy/.secrets.env
  ```
- Modify the systemd unit file at `/etc/systemd/system/caddy.service`:
  ```ini
  [Unit]
  Description=Caddy
  Documentation=https://caddyserver.com/docs/
  After=network.target network-online.target
  Requires=network-online.target

  [Service]
  Type=notify
  User=caddy
  Group=caddy
  ExecStart=/usr/bin/caddy run --environ --envfile /etc/caddy/.secrets.env --config /etc/caddy/Caddyfile
  ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile
  TimeoutStopSec=5s
  LimitNOFILE=1048576
  LimitNPROC=512
  PrivateTmp=true
  ProtectSystem=full
  AmbientCapabilities=CAP_NET_BIND_SERVICE

  [Install]
  WantedBy=multi-user.target
  ```
- Add a TLS block to your Caddyfile at `/etc/caddy/Caddyfile`:
  ```caddyfile
  <domain> {
    # ...
    tls {
      dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
  }
  ```

## Installing Wings | Pterodactyl

### Overview
- Wings is the next-generation server control plane from Pterodactyl.

### Supported Systems
- **Ubuntu**: 20.04, 22.04, 24.04
- **RHEL / Rocky Linux / AlmaLinux**: 8, 9
- **Debian**: 11, 12, 13
- **Windows**: Not supported

### System Requirements
- Requires Linux capable of running Docker containers.
- KVM is guaranteed to work.
- Check virtualization with `systemd-detect-virt`.

### Installing Docker
- Quick install:
  ```bash
  curl -sSL https://get.docker.com/ | CHANNEL=stable bash
  ```
- Ensure Docker starts on boot:
  ```bash
  sudo systemctl enable --now docker
  ```

### Setting Up Swap
- For kernels 6.1 or newer, swap is enabled by default.
- Enable swap:
  ```bash
  GRUB_CMDLINE_LINUX_DEFAULT="swapaccount=1"
  sudo update-grub
  sudo reboot
  ```

### Installing Wings
- Create directory structure and download Wings:
  ```bash
  sudo mkdir -p /etc/pterodactyl
  curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
  sudo chmod u+x /usr/local/bin/wings
  ```

### Configure and Start Wings
- Create a node on the Panel and configure with `config.yml`.
- Start Wings in debug mode:
  ```bash
  sudo wings --debug
  ```

### Daemonizing Wings
- Create `wings.service` in `/etc/systemd/system`:
  ```ini
  [Unit]
  Description=Pterodactyl Wings Daemon
  After=docker.service
  Requires=docker.service
  PartOf=docker.service

  [Service]
  User=root
  WorkingDirectory=/etc/pterodactyl
  LimitNOFILE=4096
  PIDFile=/var/run/wings/daemon.pid
  ExecStart=/usr/local/bin/wings
  Restart=on-failure
  StartLimitInterval=180
  StartLimitBurst=30
  RestartSec=5s

  [Install]
  WantedBy=multi-user.target
  ```
- Enable and start Wings:
  ```bash
  sudo systemctl enable --now wings
  ```

### Node Allocations
- Create allocations via Nodes > Allocation.
- Avoid using 127.0.0.1 for allocations.

## Introduction to Pterodactyl

### Overview
- Pterodactyl is an open-source game server management panel.
- Built with PHP, React, and Go.
- Uses Docker containers for game server isolation.

### Supported Games
- Minecraft, Rust, Terraria, Team Fortress 2, and more.
- Community-supported games include Factorio, FiveM, and others.

### Responsible Disclosure
- Open-source and open to security audits.
- Report concerns to [email protected].

## Upgrading Wings

### Overview
- Upgrading Wings is simple and quick.

### Version Requirements
- Panel and Wings versions must match.

### Steps to Upgrade
1. Stop Wings:
   ```bash
   systemctl stop wings
   ```
2. Download the updated binary:
   ```bash
   curl -L -o /usr/local/bin/wings "https://github.com/pterodactyl/wings/releases/latest/download/wings_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")"
   chmod u+x /usr/local/bin/wings
   ```
3. Restart Wings:
   ```bash
   systemctl restart wings
   ```

## Setting up MySQL for Pterodactyl

### Creating a Database for Pterodactyl
- Login to MySQL:
  ```bash
  mysql -u root -p
  ```
- Create a user and database:
  ```sql
  CREATE USER 'pterodactyl'@'127.0.0.1' IDENTIFIED BY 'somePassword';
  CREATE DATABASE panel;
  GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'127.0.0.1';
  ```

### Creating a Database Host for Nodes
- Create a MySQL user with permissions:
  ```sql
  CREATE USER 'pterodactyluser'@'127.0.0.1' IDENTIFIED BY 'somepassword';
  GRANT ALL PRIVILEGES ON *.* TO 'pterodactyluser'@'127.0.0.1' WITH GRANT OPTION;
  ```
- Allow external database access by modifying `my.cnf`:
  ```ini
  [mysqld]
  bind-address=0.0.0.0
  ```

## Additional Configuration for Pterodactyl

### Private Registries
- Authenticate against private Docker registries.

### Custom Network Interfaces
- Change network interface for containers.

### Enabling Cloudflare Proxy
- Adjust Wings port for Cloudflare proxy.

### Container PID Limit
- Set the limit for active processes in a container.

### Throttles and Limits
- Customize throttle settings for server output.

### Installer Limits
- Define resource limits for installer containers.

### Other Values
- Configure miscellaneous settings such as debug mode and timeout.
```