Cache & Queue Configuration

Configure Redis, caching, queue workers, and background job processing

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

Start Worker

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

php artisan queue:restart

php artisan queue:monitor redis:high,redis:standard,redis:low --max=100

# List failed jobs
php artisan queue:failed

# Retry failed job
php artisan queue:retry JOB_ID

# Retry all failed jobs
php artisan queue:retry all

# Delete failed job
php artisan queue:forget JOB_ID

# Clear all failed jobs
php artisan queue:flush

Installing Redis

Ubuntu/Debian

sudo apt update
sudo apt install redis-server

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

sudo yum install redis

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

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:

Ubuntu/Debian

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

sudo yum install php-pecl-redis
sudo systemctl restart php-fpm

Update your .env:

.env

REDIS_CLIENT=phpredis

Clearing Cache

Clear All Cache

php artisan cache:clear

php artisan config:clear

php artisan route:clear

php artisan view:clear

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

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.