Manual Installation Guide

This guide covers manual installation of Trexzactyl Panel without using the automated installer. Recommended for advanced users who want full control over the installation process.

Prerequisites

Before starting, ensure you have:

Ubuntu 20.04/22.04/24.04 or Debian 11/12
Root or sudo access
Domain name (for SSL)
Minimum 2GB RAM, 10GB disk space

Step 1: Install Dependencies

Update System

sudo apt update && sudo apt upgrade -y

Install Required Packages

sudo apt install -y software-properties-common curl apt-transport-https ca-certificates gnupg

Add PHP Repository

sudo add-apt-repository -y ppa:ondrej/php
sudo apt update

Install PHP 8.1 and Extensions

sudo apt install -y php8.1 php8.1-{common,cli,gd,mysql,mbstring,bcmath,xml,fpm,curl,zip}

Install Composer

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Install MariaDB

curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash
sudo apt update
sudo apt install -y mariadb-server mariadb-client

Secure MariaDB:

sudo mysql_secure_installation

Install Redis

sudo apt install -y redis-server
sudo systemctl enable --now redis-server

Install Nginx

sudo apt install -y nginx
sudo systemctl enable nginx

Step 2: Create Database

mysql -u root -p

Create database and user:

CREATE DATABASE panel;
CREATE USER 'pterodactyl'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON panel.* TO 'pterodactyl'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 3: Download Panel Files

Create Directory

sudo mkdir -p /var/www/trexzactyl
cd /var/www/trexzactyl

Download Panel

sudo curl -Lo panel.tar.gz https://github.com/Trexzactyl/trexzactyl/releases/latest/download/panel.tar.gz
sudo tar -xzvf panel.tar.gz
sudo chmod -R 755 storage/* bootstrap/cache/

Step 4: Install Dependencies

sudo composer install --no-dev --optimize-autoloader

Step 5: Environment Configuration

Copy Environment File

sudo cp .env.example .env

Generate Application Key

sudo php artisan key:generate --force

Configure Environment

Edit /var/www/trexzactyl/.env:

APP_NAME=Trexzactyl
APP_ENV=production
APP_DEBUG=false
APP_URL=https://panel.example.com

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=panel
DB_USERNAME=pterodactyl
DB_PASSWORD=your_secure_password

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_DRIVER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your_email@example.com
MAIL_PASSWORD=your_email_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME=Trexzactyl

Step 6: Database Setup

Run migrations:

sudo php artisan migrate --seed --force

Step 7: Create Admin User

sudo php artisan p:user:make

Follow the prompts to create your admin account.

Step 8: Set Permissions

sudo chown -R www-data:www-data /var/www/trexzactyl/*

Step 9: Configure Crontab

Add to crontab:

sudo crontab -e

Add this line:

* * * * * php /var/www/trexzactyl/artisan schedule:run >> /dev/null 2>&1

Step 10: Create Queue Worker Service

Create /etc/systemd/system/pteroq.service:

[Unit]
Description=Pterodactyl Queue Worker
After=redis-server.service

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/trexzactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3
StartLimitInterval=180
StartLimitBurst=30
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable --now pteroq.service

Step 11: Configure Nginx

Create /etc/nginx/sites-available/pterodactyl.conf:

server {
    listen 80;
    server_name panel.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name panel.example.com;

    root /var/www/trexzactyl/public;
    index index.php;

    access_log /var/log/nginx/trexzactyl.app-access.log;
    error_log  /var/log/nginx/trexzactyl.app-error.log error;

    client_max_body_size 100m;
    client_body_timeout 120s;

    sendfile off;

    ssl_certificate /etc/letsencrypt/live/panel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;
    ssl_session_cache shared:SSL:10m;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384";
    ssl_prefer_server_ciphers on;

    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
    add_header X-Robots-Tag none;
    add_header Content-Security-Policy "frame-ancestors 'self'";
    add_header X-Frame-Options DENY;
    add_header Referrer-Policy same-origin;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/run/php/php8.1-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;
        include /etc/nginx/fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Enable site:

sudo ln -s /etc/nginx/sites-available/pterodactyl.conf /etc/nginx/sites-enabled/pterodactyl.conf
sudo nginx -t
sudo systemctl restart nginx

Step 12: Install SSL Certificate

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d panel.example.com

Step 13: Install Node.js and Build Assets

Install Node.js

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Build Frontend Assets

cd /var/www/trexzactyl
npm install
npm run build:production

Step 14: Final Steps

Clear Cache

cd /var/www/trexzactyl
php artisan config:clear
php artisan cache:clear
php artisan view:clear

Restart Services

sudo systemctl restart nginx
sudo systemctl restart php8.1-fpm
sudo systemctl restart pteroq

Verification

Visit your panel URL: https://panel.example.com
Login with your admin credentials
Check that all services are running:

sudo systemctl status nginx
sudo systemctl status php8.1-fpm
sudo systemctl status pteroq
sudo systemctl status redis-server
sudo systemctl status mariadb

Troubleshooting

Permission Issues

sudo chown -R www-data:www-data /var/www/trexzactyl/*
sudo chmod -R 755 /var/www/trexzactyl/storage
sudo chmod -R 755 /var/www/trexzactyl/bootstrap/cache

Queue Worker Not Running

sudo systemctl status pteroq
sudo journalctl -u pteroq -n 50

Database Connection Failed

Verify credentials in .env file and test connection:

mysql -u pterodactyl -p panel

White Screen / 500 Error

Check logs:

tail -f /var/log/nginx/trexzactyl.app-error.log
tail -f /var/www/trexzactyl/storage/logs/laravel.log

Next Steps

After panel installation:

Install Wings on your game server nodes
Configure SSL if not already done
Set up backups
Configure email

Automated Alternative

For easier installation, use the automated installer:

bash <(curl -s http://installer.trexz.xyz/install.sh)

The automated installer handles all these steps automatically with proper error checking and validation.