Cache & Queue Configuration - Pterodactyl Panel

Pterodactyl Panel uses caching to improve performance and queues for asynchronous job processing. Redis is the recommended backend for both.

Redis Configuration

Basic Redis Setup

.env

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=null
REDIS_CLIENT=predis

REDIS_HOST

string

default:"127.0.0.1"

Redis server hostname or IP address.

REDIS_PORT

integer

default:"6379"

Redis server port.

REDIS_PASSWORD

string

Redis authentication password. Use null for no authentication.

Always set a strong password for Redis in production environments.

REDIS_CLIENT

string

default:"predis"

Redis client library. Options:

predis - Pure PHP implementation (default)
phpredis - PHP extension (faster, requires installation)

Advanced Redis Configuration

.env

REDIS_SCHEME=tcp
REDIS_PATH=/run/redis/redis.sock
REDIS_USERNAME=default
REDIS_DATABASE=0
REDIS_DATABASE_SESSIONS=1

REDIS_SCHEME

string

default:"tcp"

Connection scheme. Options: tcp, unix

REDIS_PATH

string

Path to Unix socket when using REDIS_SCHEME=unix. Provides better performance for local Redis.

REDIS_USERNAME

string

Redis username for ACL authentication (Redis 6.0+).

REDIS_DATABASE

integer

default:"0"

Redis database number for general cache and queue data.

REDIS_DATABASE_SESSIONS

integer

default:"1"

Redis database number for session storage (when using Redis sessions).

Redis Clustering

.env

REDIS_CLUSTER=redis
REDIS_PREFIX=pterodactyl_

REDIS_CLUSTER

string

default:"redis"

Redis cluster mode. Options: redis, predis

REDIS_PREFIX

string

Prefix for all Redis keys. Automatically generated from APP_NAME if not set.

Redis SSL/TLS

For secure Redis connections:

.env

REDIS_VERIFY_PEER=true
REDIS_VERIFY_PEER_NAME=true
REDIS_CAFILE=/path/to/ca-cert.pem
REDIS_LOCAL_CERT=/path/to/client-cert.pem
REDIS_LOCAL_PK=/path/to/client-key.pem

SSL configuration only works with the phpredis client.

Cache Configuration

Cache Driver Selection

.env

CACHE_DRIVER=redis
CACHE_PREFIX=pterodactyl_cache_

CACHE_DRIVER

string

default:"redis"

Cache storage driver. Options:

redis - Redis (recommended)
file - Filesystem storage
database - Database storage
memcached - Memcached
array - In-memory (testing only)

CACHE_PREFIX

string

Prefix for cache keys. Auto-generated from APP_NAME if not set.

File Cache

For development or small deployments:

.env

CACHE_DRIVER=file

Cache files are stored in storage/framework/cache/data/.

Database Cache

Store cache in the database:

.env

CACHE_DRIVER=database
DB_CACHE_CONNECTION=mysql
DB_CACHE_TABLE=cache

Database caching is slower than Redis but doesn’t require additional services.

Memcached Configuration

.env

CACHE_DRIVER=memcached
MEMCACHED_HOST=127.0.0.1
MEMCACHED_PORT=11211
MEMCACHED_USERNAME=
MEMCACHED_PASSWORD=

Redis Cache Connection

.env

REDIS_CACHE_CONNECTION=default
REDIS_CACHE_LOCK_CONNECTION=default

REDIS_CACHE_CONNECTION

string

default:"default"

Redis connection to use for caching.

REDIS_CACHE_LOCK_CONNECTION

string

default:"default"

Redis connection to use for cache locks.

Queue Configuration

Queue Driver Selection

.env

QUEUE_CONNECTION=redis

QUEUE_CONNECTION

string

default:"redis"

Queue backend driver. Options:

redis - Redis (recommended)
database - Database storage
sync - Synchronous (no queuing, development only)
beanstalkd - Beanstalkd queue
sqs - Amazon SQS

Redis Queue Configuration

.env

QUEUE_CONNECTION=redis
REDIS_QUEUE_CONNECTION=default
REDIS_QUEUE=standard
REDIS_QUEUE_RETRY_AFTER=90

REDIS_QUEUE_CONNECTION

string

default:"default"

Redis connection to use for queues.

REDIS_QUEUE

string

default:"standard"

Default queue name.

REDIS_QUEUE_RETRY_AFTER

integer

default:"90"

Seconds after which a job is retried if a worker dies.

Database Queue Configuration

.env

QUEUE_CONNECTION=database
DB_QUEUE_CONNECTION=mysql
DB_QUEUE_TABLE=jobs
DB_QUEUE=standard
DB_QUEUE_RETRY_AFTER=90

Database queues require the jobs and failed_jobs tables. Run migrations to create them.

Failed Jobs Configuration

.env

QUEUE_FAILED_DRIVER=database-uuids

QUEUE_FAILED_DRIVER

string

default:"database-uuids"

Storage for failed jobs. Options:

database-uuids - Database with UUID identifiers
file - Filesystem storage
null - Discard failed jobs

Session Storage

Session Driver Selection

.env

SESSION_DRIVER=redis
SESSION_LIFETIME=720

SESSION_DRIVER

string

default:"redis"

Session storage driver. Options:

redis - Redis (recommended)
database - Database storage
file - Filesystem storage
cookie - Browser cookies

SESSION_LIFETIME

integer

default:"720"

Session lifetime in minutes (12 hours by default).

Redis Session Configuration

.env

SESSION_DRIVER=redis
SESSION_CONNECTION=sessions

Redis sessions use the sessions connection, which points to REDIS_DATABASE_SESSIONS.

Database Session Configuration

.env

SESSION_DRIVER=database
SESSION_TABLE=sessions
SESSION_CONNECTION=mysql

Queue Worker Setup

Running Queue Workers

Queue workers process background jobs. Run them with:

php artisan queue:work --queue=high,standard,low --tries=3

Supervisor Configuration

Use Supervisor to keep queue workers running:

/etc/supervisor/conf.d/pterodactyl-worker.conf

[program:pterodactyl-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/pterodactyl/storage/logs/queue-worker.log
stopwaitsecs=3600

Reload Supervisor after creating the config:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start pterodactyl-worker:*

Systemd Service

Alternatively, use systemd:

/etc/systemd/system/pterodactyl-worker.service

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

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/pterodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3 --max-time=3600
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable pterodactyl-worker
sudo systemctl start pterodactyl-worker

Worker Commands

php artisan queue:work --queue=high,standard,low --tries=3

Installing Redis

sudo apt update
sudo apt install redis-server

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

Securing Redis

Edit /etc/redis/redis.conf:

/etc/redis/redis.conf

# Set a password
requirepass your_strong_password_here

# Bind to localhost only (if Panel is on same server)
bind 127.0.0.1

# Disable dangerous commands
rename-command FLUSHDB ""
rename-command FLUSHALL ""
rename-command CONFIG ""

Restart Redis:

sudo systemctl restart redis-server

Installing PHPRedis Extension

For better performance, install the phpredis extension:

sudo apt install php-redis
sudo systemctl restart php8.3-fpm

Update your .env:

.env

REDIS_CLIENT=phpredis

Clearing Cache

php artisan cache:clear

Performance Optimization

Cache Configuration

In production, cache configuration files:

php artisan config:cache
php artisan route:cache
php artisan view:cache

After caching, changes to .env won’t take effect until you run php artisan config:clear.

Multiple Queue Workers

Run multiple workers for better throughput:

# In supervisor config
numprocs=4

Or run workers for different queues:

php artisan queue:work --queue=high --tries=3
php artisan queue:work --queue=standard --tries=3
php artisan queue:work --queue=low --tries=3

Troubleshooting

Redis Connection Refused

Solutions:

# Check if Redis is running
sudo systemctl status redis-server

# Test Redis connection
redis-cli ping
# Should return: PONG

# Test with password
redis-cli -a your_password ping

Queue Jobs Not Processing

Possible causes:

Queue workers not running
Worker died/crashed
Queue connection misconfigured

Solutions:

# Check supervisor status
sudo supervisorctl status pterodactyl-worker:*

# Restart workers
php artisan queue:restart

# Check worker logs
tail -f storage/logs/queue-worker.log

Session Data Lost

Possible causes:

Redis not running
Session lifetime too short
Different Redis database

Solutions:

# Verify session driver
php artisan tinker
>>> config('session.driver')

# Check Redis sessions database
redis-cli
> SELECT 1
> KEYS *session*

Cache Not Working

Solutions:

# Test cache
php artisan tinker
>>> Cache::put('test', 'value', 60)
>>> Cache::get('test')

# Clear and rebuild cache
php artisan cache:clear
php artisan config:cache

Monitoring

Redis Monitoring

# Monitor Redis commands in real-time
redis-cli monitor

# Get Redis info
redis-cli info

# Check memory usage
redis-cli info memory

# List all keys (careful in production!)
redis-cli --scan

Queue Monitoring

# Monitor queue size
php artisan queue:monitor redis:standard --max=100

# View failed jobs
php artisan queue:failed

# Queue statistics
php artisan queue:work --queue=standard --once --verbose

Best Practices

Use Redis

Redis provides the best performance for cache, queues, and sessions.

Run Queue Workers

Always run queue workers in production for background job processing.

Monitor Workers

Use Supervisor or systemd to keep queue workers running and auto-restart on failure.

Secure Redis

Always set a password and bind to localhost when possible.

Getting Started

Panel Administration

Server Management

User Guide

Configuration

Advanced

​Redis Configuration

​Basic Redis Setup

​Advanced Redis Configuration

​Redis Clustering

​Redis SSL/TLS

​Cache Configuration

​Cache Driver Selection

​File Cache

​Database Cache

​Memcached Configuration

​Redis Cache Connection

​Queue Configuration

​Queue Driver Selection

​Redis Queue Configuration

​Database Queue Configuration

​Failed Jobs Configuration

​Session Storage

​Session Driver Selection

​Redis Session Configuration

​Database Session Configuration

​Queue Worker Setup

​Running Queue Workers

​Supervisor Configuration

​Systemd Service

​Worker Commands

​Installing Redis

​Securing Redis

​Installing PHPRedis Extension

​Clearing Cache

​Performance Optimization

​Cache Configuration

​Multiple Queue Workers

​Troubleshooting

​Monitoring

​Redis Monitoring

​Queue Monitoring

​Best Practices

Use Redis

Run Queue Workers

Monitor Workers

Secure Redis

Build docs developers (and LLMs) love

Redis Configuration

Basic Redis Setup

Advanced Redis Configuration

Redis Clustering

Redis SSL/TLS

Cache Configuration

Cache Driver Selection

File Cache

Database Cache

Memcached Configuration

Redis Cache Connection

Queue Configuration

Queue Driver Selection

Redis Queue Configuration

Database Queue Configuration

Failed Jobs Configuration

Session Storage

Session Driver Selection

Redis Session Configuration

Database Session Configuration

Queue Worker Setup

Running Queue Workers

Supervisor Configuration

Systemd Service

Worker Commands

Installing Redis

Securing Redis

Installing PHPRedis Extension

Clearing Cache

Performance Optimization

Cache Configuration

Multiple Queue Workers

Troubleshooting

Monitoring

Redis Monitoring

Queue Monitoring

Best Practices