Configuration

XyraPanel is configured entirely through environment variables stored in the .env file. This guide explains all available configuration options.

Environment File Location

/opt/xyrapanel/.env

Essential Configuration

These variables must be configured before running XyraPanel.

Application Settings

.env

APP_NAME="XyraPanel"
NODE_ENV="production"
DEBUG=false

APP_NAME

string

default:"XyraPanel"

The display name of your panel. Shown in the UI and emails.

NODE_ENV

string

default:"production"

Environment mode. Use production for live deployments, development for local testing.

DEBUG

boolean

default:"false"

Enable debug logging. Only use in development.

Application URLs

.env

BETTER_AUTH_URL=https://panel.example.com
BETTER_AUTH_TRUSTED_ORIGINS=https://panel.example.com
NUXT_PUBLIC_APP_URL=https://panel.example.com
PANEL_PUBLIC_URL="https://panel.example.com"
PANEL_INTERNAL_URL="http://127.0.0.1:3000"
PORT="3000"

BETTER_AUTH_URL

string

required

Public URL where your panel is accessible. Must include protocol (https://).

BETTER_AUTH_TRUSTED_ORIGINS

string

required

Comma-separated list of trusted origins for authentication. Typically matches BETTER_AUTH_URL.

NUXT_PUBLIC_APP_URL

string

required

Public-facing application URL. Used for client-side routing.

PANEL_PUBLIC_URL

string

required

External URL used in emails and API responses.

PANEL_INTERNAL_URL

string

default:"http://127.0.0.1:3000"

Internal URL for server-to-server communication.

PORT

number

default:"3000"

Port the application listens on. Nginx proxies to this port.

Authentication Secrets

Security Critical: Generate strong, unique secrets for production. Never share these values.

.env

# Generate with: openssl rand -base64 32
BETTER_AUTH_SECRET=<your-generated-secret>
SEED_SECRET=<your-generated-secret>

BETTER_AUTH_SECRET

string

required

Secret key for authentication token signing. Generate with openssl rand -base64 32.

Changing this will invalidate all existing sessions.

SEED_SECRET

string

required

Secret used to protect the admin seed endpoint. Required for creating the initial admin account.

Admin Account Seeding

.env

SEED_ADMIN_EMAIL="admin@example.com"
SEED_ADMIN_PASSWORD="changeme"
SEED_ADMIN_USERNAME="admin"
SEED_ADMIN_NAME="Admin"

SEED_ADMIN_EMAIL

string

required

Email address for the initial admin account.

SEED_ADMIN_PASSWORD

string

required

Password for the initial admin account. Change this immediately after first login.

SEED_ADMIN_USERNAME

string

required

Username for the admin account.

SEED_ADMIN_NAME

string

required

Display name for the admin user.

Database Configuration

.env

# PostgreSQL connection string
DATABASE_URL="postgresql://xyra:changeme@postgres:5432/xyrapanel"

# Docker only: these configure the postgres container
DB_USER="xyra"
DB_PASSWORD="changeme"
DB_NAME="xyrapanel"

DATABASE_URL

string

required

PostgreSQL connection string. Format:

postgresql://[user]:[password]@[host]:[port]/[database]

Examples:

Docker: postgresql://xyra:changeme@postgres:5432/xyrapanel
Manual: postgresql://xyra:changeme@127.0.0.1:5432/xyrapanel

DB_USER

string

default:"xyra"

Database username. Docker only - must match credentials in DATABASE_URL.

DB_PASSWORD

string

required

Database password. Docker only - must match credentials in DATABASE_URL.

DB_NAME

string

default:"xyrapanel"

Database name. Docker only - must match database in DATABASE_URL.

Redis Configuration

.env

REDIS_HOST="redis"
REDIS_PORT="6379"
# REDIS_USERNAME=""  # Optional
# REDIS_PASSWORD=""  # Optional
# REDIS_TLS="false"  # Optional

REDIS_HOST

string

required

Redis server hostname.

Docker: redis
Manual: 127.0.0.1 or localhost

REDIS_PORT

number

default:"6379"

Redis server port.

REDIS_USERNAME

string

Redis username (ACL). Leave empty if not using authentication.

REDIS_PASSWORD

string

Redis password. Leave empty if not using authentication.

REDIS_TLS

boolean

default:"false"

Enable TLS for Redis connection. Set to true for managed Redis services.

Advanced Configuration

Nuxt/Nitro Redis Storage

Internal caching configuration. Must match your Redis settings.

.env

NITRO_STORAGE_CACHE_DRIVER="redis"
NITRO_STORAGE_CACHE_HOST="redis"
NITRO_STORAGE_CACHE_PORT="6379"
NUXT_REDIS_HOST="redis"
NUXT_REDIS_PORT="6379"

Security Settings

.env

NUXT_SECURITY_CORS_ORIGIN="https://panel.example.com"
NUXT_SECURITY_CONNECT_SRC="https://panel.example.com"
NUXT_SECURITY_RATE_LIMIT_DRIVER="redis"
NUXT_SECURITY_RATE_LIMIT_TOKENS="150"
NUXT_SECURITY_RATE_LIMIT_INTERVAL_MS="300000"
NUXT_SECURITY_CSP_REPORT_ONLY="false"
NUXT_SECURITY_CSP_REPORT_URI=""

NUXT_SECURITY_CORS_ORIGIN

string

required

Allowed CORS origin. Should match your panel URL.

NUXT_SECURITY_RATE_LIMIT_DRIVER

string

default:"redis"

Rate limiting storage driver. Use redis in production, lruCache for development.

NUXT_SECURITY_RATE_LIMIT_TOKENS

number

default:"150"

Number of requests allowed per interval.

NUXT_SECURITY_RATE_LIMIT_INTERVAL_MS

number

default:"300000"

Rate limit interval in milliseconds (default: 5 minutes).

NUXT_SECURITY_CSP_REPORT_ONLY

boolean

default:"false"

Content Security Policy mode.

true: Report violations without blocking (testing)
false: Enforce CSP and block violations (production)

HTTP Cache Settings

.env

NUXT_HTTP_CACHE_ENABLED="true"
NUXT_HTTP_CACHE_DEFAULT_MAX_AGE="5"
NUXT_HTTP_CACHE_DEFAULT_SWR="15"
NUXT_HTTP_CACHE_DASHBOARD_MAX_AGE="10"
NUXT_HTTP_CACHE_DASHBOARD_SWR="30"

NUXT_HTTP_CACHE_ENABLED

boolean

default:"true"

Enable HTTP response caching for improved performance.

NUXT_HTTP_CACHE_DEFAULT_MAX_AGE

number

default:"5"

Default cache max-age in seconds.

NUXT_HTTP_CACHE_DEFAULT_SWR

number

default:"15"

Stale-while-revalidate duration in seconds.

Captcha Configuration

XyraPanel supports Cloudflare Turnstile, Google reCAPTCHA v3, and hCaptcha.

Cloudflare Turnstile
Google reCAPTCHA v3
hCaptcha

.env

CAPTCHA_PROVIDER="turnstile"
NUXT_TURNSTILE_SECRET_KEY="your-secret-key"
NUXT_PUBLIC_TURNSTILE_SITE_KEY="your-site-key"

Get your keys at: Cloudflare Turnstile

Test mode key: 1x00000000000000000000AA (allows testing without validation)

.env

CAPTCHA_PROVIDER="recaptcha"
NUXT_RECAPTCHA_SECRET_KEY="your-secret-key"
NUXT_RECAPTCHA_MIN_SCORE="0.5"

Get your keys at: Google reCAPTCHA Admin

.env

CAPTCHA_PROVIDER="hcaptcha"
NUXT_HCAPTCHA_SECRET_KEY="your-secret-key"
NUXT_HCAPTCHA_SITE_KEY="your-site-key"

Get your keys at: hCaptcha Dashboard

Request Limits

.env

NUXT_MAX_REQUEST_SIZE_MB="10"
NUXT_MAX_UPLOAD_SIZE_MB="20"

NUXT_MAX_REQUEST_SIZE_MB

number

default:"10"

Maximum request body size in megabytes.

NUXT_MAX_UPLOAD_SIZE_MB

number

default:"20"

Maximum file upload size in megabytes.

PM2 Configuration

.env

# INSTANCES=1  # Uncomment to force single instance
# MAX_MEMORY_RESTART="1G"  # Restart if memory exceeds limit

INSTANCES

number

default:"max"

Number of PM2 instances to run.

max: Use all CPU cores (default)
1: Single instance (recommended for servers with less than 2GB RAM)
<number>: Specific number of instances

MAX_MEMORY_RESTART

string

default:"1G"

Restart instance if memory usage exceeds this limit. Format: <number>G or <number>M.

Configuration Examples

Development Setup

.env

APP_NAME="XyraPanel Dev"
NODE_ENV="development"
DEBUG=true

BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3000
NUXT_PUBLIC_APP_URL=http://localhost:3000
PANEL_PUBLIC_URL="http://localhost:3000"
PANEL_INTERNAL_URL="http://127.0.0.1:3000"
PORT="3000"

BETTER_AUTH_SECRET=<generated-secret>
SEED_SECRET=<generated-secret>

SEED_ADMIN_EMAIL="dev@localhost"
SEED_ADMIN_PASSWORD="admin"
SEED_ADMIN_USERNAME="admin"
SEED_ADMIN_NAME="Dev Admin"

DATABASE_URL="postgresql://xyra:changeme@localhost:5432/xyrapanel"

REDIS_HOST="localhost"
REDIS_PORT="6379"

NUXT_SECURITY_RATE_LIMIT_DRIVER="lruCache"
CAPTCHA_PROVIDER="turnstile"
NUXT_PUBLIC_TURNSTILE_SITE_KEY="1x00000000000000000000AA"

Production Setup

.env

APP_NAME="XyraPanel"
NODE_ENV="production"
DEBUG=false

BETTER_AUTH_URL=https://panel.yourdomain.com
BETTER_AUTH_TRUSTED_ORIGINS=https://panel.yourdomain.com
NUXT_PUBLIC_APP_URL=https://panel.yourdomain.com
PANEL_PUBLIC_URL="https://panel.yourdomain.com"
PANEL_INTERNAL_URL="http://127.0.0.1:3000"
PORT="3000"

BETTER_AUTH_SECRET=<strong-generated-secret>
SEED_SECRET=<strong-generated-secret>

SEED_ADMIN_EMAIL="admin@yourdomain.com"
SEED_ADMIN_PASSWORD="<strong-password>"
SEED_ADMIN_USERNAME="admin"
SEED_ADMIN_NAME="Administrator"

DATABASE_URL="postgresql://xyrapanel:<secure-password>@127.0.0.1:5432/xyrapanel"

REDIS_HOST="127.0.0.1"
REDIS_PORT="6379"
REDIS_PASSWORD="<redis-password>"

NUXT_SECURITY_CORS_ORIGIN="https://panel.yourdomain.com"
NUXT_SECURITY_RATE_LIMIT_DRIVER="redis"
NUXT_SECURITY_RATE_LIMIT_TOKENS="1000"
NUXT_SECURITY_CSP_REPORT_ONLY="false"

CAPTCHA_PROVIDER="turnstile"
NUXT_TURNSTILE_SECRET_KEY="<your-turnstile-secret>"
NUXT_PUBLIC_TURNSTILE_SITE_KEY="<your-turnstile-site-key>"

INSTANCES=2
MAX_MEMORY_RESTART="1G"

Applying Configuration Changes

After modifying .env, restart the panel:

pm2 restart xyrapanel

Security Best Practices

Generate Strong Secrets

Always generate cryptographically secure secrets:

# Generate BETTER_AUTH_SECRET
openssl rand -base64 32

# Generate SEED_SECRET
openssl rand -base64 32

# Generate database password
openssl rand -hex 16

Protect Your .env File

Ensure proper file permissions:

chmod 600 /opt/xyrapanel/.env
chown xyrapanel:xyrapanel /opt/xyrapanel/.env

Never commit .env to version control. Add it to .gitignore.

Use HTTPS in Production

Always use https:// URLs for production deployments:

BETTER_AUTH_URL
NUXT_PUBLIC_APP_URL
PANEL_PUBLIC_URL

Use Let’s Encrypt for free SSL certificates.

Enable Rate Limiting

Use Redis-based rate limiting in production:

NUXT_SECURITY_RATE_LIMIT_DRIVER="redis"
NUXT_SECURITY_RATE_LIMIT_TOKENS="1000"

Rotate Secrets Regularly

Implement a secret rotation policy:

Generate new BETTER_AUTH_SECRET
Update .env
Restart the panel
All users will need to re-authenticate

Next Steps

First Server

Create your first game server

Wings Setup

Install and configure Wings daemon

Overview

Getting Started

Server Management

Administration

CLI

Advanced

Configuration

Environment File Location

Essential Configuration

Application Settings

Application URLs

Authentication Secrets

Admin Account Seeding

Database Configuration

Redis Configuration

Advanced Configuration

Nuxt/Nitro Redis Storage

Security Settings

HTTP Cache Settings

Captcha Configuration

Request Limits

PM2 Configuration

Configuration Examples

Development Setup

Production Setup

Applying Configuration Changes

Security Best Practices

Next Steps

First Server

Wings Setup

Build docs developers (and LLMs) love

Overview

Getting Started

Server Management

Administration

Configuration

CLI

Advanced

Documentation Index

​Environment File Location

​Essential Configuration

​Application Settings

​Application URLs

​Authentication Secrets

​Admin Account Seeding

​Database Configuration

​Redis Configuration

​Advanced Configuration

​Nuxt/Nitro Redis Storage

​Security Settings

​HTTP Cache Settings

​Captcha Configuration

​Request Limits

​PM2 Configuration

​Configuration Examples

​Development Setup

​Production Setup

​Applying Configuration Changes

​Security Best Practices

​Next Steps

First Server

Wings Setup

Build docs developers (and LLMs) love

Environment File Location

Essential Configuration

Application Settings

Application URLs

Authentication Secrets

Admin Account Seeding

Database Configuration

Redis Configuration

Advanced Configuration

Nuxt/Nitro Redis Storage

Security Settings

HTTP Cache Settings

Captcha Configuration

Request Limits

PM2 Configuration

Configuration Examples

Development Setup

Production Setup

Applying Configuration Changes

Security Best Practices

Next Steps