Installation

XyraPanel is an open-source game server management panel built on Nuxt, TypeScript, and PostgreSQL. This guide covers three installation methods to get your panel up and running.

Early Access: XyraPanel is under active development. APIs, UI, and behavior will change. Not recommended for production use yet.

System Requirements

Minimum Requirements

RAM: 512MB minimum, 2GB+ recommended
OS: Ubuntu 22.04/24.04, Debian 11/12, AlmaLinux 8/9
Disk: 10GB+ available space
CPU: 1 core minimum, 2+ recommended

Software Dependencies

Node.js 22.x
PostgreSQL 16+
Redis 7+
Nginx (with SSL/TLS)
PM2 (process manager)

One-Line Installer (Recommended)

The automated installer handles all dependencies, configuration, and setup for Ubuntu and Debian-based systems.

Run the Installer

Execute the following command as root:

bash <(curl -fsSL https://xyrapanel.com/install)

The installer must be run as root or with sudo. It will detect your OS and install appropriate dependencies.

Choose Installation Type

The installer will present a menu:

[1] Install - Fresh installation
[2] Update - Update existing installation
[3] Reinstall - Wipe and clean install
[4] Uninstall - Remove XyraPanel completely

For first-time setup, choose option 1.

Provide Configuration Details

The installer will prompt for:

Domain: Your panel’s domain (e.g., panel.example.com)
Admin Email: Primary administrator email
Admin Username: Admin account username
Admin Password: Secure password (will be prompted twice)
Database Password: PostgreSQL password (auto-generated by default)
Let’s Encrypt Email: For SSL certificate notifications

Ensure your domain’s DNS A record points to your server’s IP address before running the installer for automatic SSL certificate generation.

Wait for Installation

The installer will:

Install system dependencies (Node.js, PostgreSQL, Redis, Nginx)
Configure firewall rules (ports 22, 80, 443, 8080)
Clone the XyraPanel repository to /opt/xyrapanel
Build the application
Set up SSL certificates with Let’s Encrypt
Start the panel with PM2
Seed the admin account

This process typically takes 5-10 minutes depending on your server’s resources.

Access Your Panel

Once complete, access your panel at:

https://your-domain.com

Post-Installation Commands

# Check panel status
pm2 status

# View panel logs
pm2 logs xyrapanel

# Restart the panel
pm2 restart xyrapanel

# Check Nginx status
systemctl status nginx

# View database status
sudo systemctl status postgresql

Docker Installation

Run XyraPanel in a containerized environment using Docker Compose.

Prerequisites

Install Docker and Docker Compose on your system:

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt-get install docker-compose-plugin

Clone the Repository

git clone https://github.com/XyraPanel/panel.git xyrapanel
cd xyrapanel

Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env and configure the essential variables:

.env

# Application URLs
BETTER_AUTH_URL=https://your-domain.com
BETTER_AUTH_TRUSTED_ORIGINS=https://your-domain.com
NUXT_PUBLIC_APP_URL=https://your-domain.com
PANEL_PUBLIC_URL="https://your-domain.com"

# Generate secrets
BETTER_AUTH_SECRET=<run: openssl rand -base64 32>
SEED_SECRET=<run: openssl rand -base64 32>

# Admin account
SEED_ADMIN_EMAIL="[email protected]"
SEED_ADMIN_PASSWORD="changeme"
SEED_ADMIN_USERNAME="admin"

# Database (must match docker-compose.yml)
DATABASE_URL="postgresql://xyra:changeme@postgres:5432/xyrapanel"
DB_USER="xyra"
DB_PASSWORD="changeme"
DB_NAME="xyrapanel"

See the Configuration Guide for detailed information on all environment variables.

Configure SSL Certificates

Update nginx/nginx.conf with your domain, then obtain certificates:

# Start services
docker compose up -d

# Request SSL certificate
docker compose run --rm certbot certonly --webroot \
  -w /var/www/certbot \
  --cert-name panel \
  -d your-domain.com \
  --email [email protected] \
  --agree-tos \
  --no-eff-email

# Restart Nginx to apply certificates
docker compose restart nginx

Seed Admin Account

Create the initial admin account:

# Get your SEED_SECRET from .env
SEED_SECRET=$(grep '^SEED_SECRET=' .env | cut -d '=' -f2)

# Seed the admin account
curl -X POST http://localhost:3000/api/system/seed \
  -H "Authorization: Bearer $SEED_SECRET" \
  -H "Content-Type: application/json"

Access the Panel

Navigate to https://your-domain.com and login with your admin credentials.

Docker Management Commands

# View running containers
docker compose ps

# View logs
docker compose logs -f app

# Restart all services
docker compose restart

# Stop all services
docker compose down

# Update and rebuild
git pull
docker compose build --no-cache
docker compose up -d

Manual Installation

For advanced users who want full control over the installation process.

Install System Dependencies

# Ubuntu/Debian
sudo apt update
sudo apt install -y curl wget git ca-certificates gnupg \
  lsb-release openssl build-essential python3

Install Node.js 22

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -

# Install Node.js
sudo apt install -y nodejs

# Verify installation
node -v  # Should show v22.x.x

Install pnpm and PM2

# Install pnpm
curl -fsSL https://github.com/pnpm/pnpm/releases/latest/download/pnpm-linux-x64 \
  -o /usr/local/bin/pnpm
chmod +x /usr/local/bin/pnpm

# Install PM2 globally
sudo npm install -g pm2@latest

# Setup PM2 startup script
pm2 startup systemd

Install PostgreSQL 16

# Add PostgreSQL repository
curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | \
  sudo gpg --dearmor -o /usr/share/keyrings/postgresql.gpg

echo "deb [signed-by=/usr/share/keyrings/postgresql.gpg] \
  https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | \
  sudo tee /etc/apt/sources.list.d/pgdg.list

sudo apt update
sudo apt install -y postgresql-16

# Create database and user
sudo -u postgres psql <<EOF
CREATE USER xyrapanel WITH PASSWORD 'your_secure_password';
CREATE DATABASE xyrapanel OWNER xyrapanel;
GRANT ALL PRIVILEGES ON DATABASE xyrapanel TO xyrapanel;
EOF

Install Redis

sudo apt install -y redis-server

# Configure Redis to bind to localhost
sudo sed -i 's/^bind .*/bind 127.0.0.1/' /etc/redis/redis.conf

# Enable and start Redis
sudo systemctl enable redis-server
sudo systemctl start redis-server

Install Nginx and Certbot

sudo apt install -y nginx certbot python3-certbot-nginx

# Enable Nginx
sudo systemctl enable nginx

Clone and Build XyraPanel

# Create system user
sudo useradd --system --shell /bin/bash --create-home \
  --home-dir /opt/xyrapanel xyrapanel

# Clone repository
sudo git clone https://github.com/XyraPanel/panel.git /opt/xyrapanel
cd /opt/xyrapanel

# Create .env file (see Configuration guide)
sudo cp .env.example .env
sudo nano .env  # Edit with your settings

# Install dependencies
sudo -u xyrapanel pnpm install --frozen-lockfile

# Generate PWA assets
sudo -u xyrapanel pnpm run generate-pwa-assets

# Build the application
sudo -u xyrapanel NODE_OPTIONS="--max-old-space-size=4096" pnpm build

# Set permissions
sudo chown -R xyrapanel:xyrapanel /opt/xyrapanel

Configure Nginx

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

server {
    listen 80;
    server_name your-domain.com;
    location /.well-known/acme-challenge/ { root /var/www/certbot; }
    location / { return 301 https://$host$request_uri; }
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    client_max_body_size 25M;
    proxy_read_timeout   300s;

    location / {
        proxy_pass         http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection 'upgrade';
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the configuration:

sudo ln -s /etc/nginx/sites-available/xyrapanel.conf \
  /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Obtain SSL Certificate

sudo mkdir -p /var/www/certbot
sudo certbot certonly --webroot -w /var/www/certbot \
  -d your-domain.com \
  --email [email protected] \
  --agree-tos --no-eff-email

sudo systemctl reload nginx

Start the Panel with PM2

cd /opt/xyrapanel

# Start with PM2
sudo -u xyrapanel pm2 start .output/server/index.mjs \
  --name xyrapanel -i 1

# Save PM2 configuration
sudo -u xyrapanel pm2 save

# Enable PM2 startup
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u xyrapanel --hp /opt/xyrapanel

Seed Admin Account

# Get SEED_SECRET from .env
SEED_SECRET=$(sudo grep '^SEED_SECRET=' /opt/xyrapanel/.env | cut -d '=' -f2)

# Create admin account
curl -X POST http://127.0.0.1:3000/api/system/seed \
  -H "Authorization: Bearer $SEED_SECRET" \
  -H "Content-Type: application/json"

Next Steps

Configuration

Learn about environment variables and configuration options

First Server

Create your first game server

Troubleshooting

Installation fails with “Insufficient RAM”

The installer requires at least 512MB of RAM. If you have less, consider:

Upgrading your server
Creating swap space: sudo fallocate -l 2G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

SSL certificate generation fails

Ensure your domain’s DNS A record points to your server’s IP address:

dig +short your-domain.com

If DNS is correct but certificate fails, manually request it:

sudo certbot certonly --webroot -w /var/www/certbot \
  -d your-domain.com --email [email protected] --agree-tos

Panel won’t start

Check PM2 logs for errors:

pm2 logs xyrapanel --lines 100

Verify PostgreSQL and Redis are running:

sudo systemctl status postgresql
sudo systemctl status redis-server

Verify the admin account was seeded:

sudo -u postgres psql -d xyrapanel -c "SELECT email, username FROM users WHERE role = 'admin';"

If no admin exists, re-run the seed command with your SEED_SECRET.

Overview

Getting Started

Server Management

Administration

Configuration

CLI

Advanced

System Requirements

Minimum Requirements

Software Dependencies

One-Line Installer (Recommended)

Post-Installation Commands

Docker Installation

Docker Management Commands

Manual Installation

Next Steps

Configuration

First Server

Troubleshooting

Installation fails with “Insufficient RAM”

SSL certificate generation fails

Panel won’t start

Build docs developers (and LLMs) love

Overview

Getting Started

Server Management

Administration

Configuration

CLI

Advanced

​System Requirements

Minimum Requirements

Software Dependencies

​One-Line Installer (Recommended)

​Post-Installation Commands

​Docker Installation

​Docker Management Commands

​Manual Installation

​Next Steps

Configuration

First Server

​Troubleshooting

​Installation fails with “Insufficient RAM”

​SSL certificate generation fails

​Panel won’t start

​Cannot login after installation

Build docs developers (and LLMs) love

System Requirements

One-Line Installer (Recommended)

Post-Installation Commands

Docker Installation

Docker Management Commands

Manual Installation

Next Steps

Troubleshooting

Installation fails with “Insufficient RAM”

SSL certificate generation fails

Panel won’t start

Cannot login after installation