Additional Configuration

Once your panel is installed and accessible, configure additional services for caching, email delivery, Blueprint extensions, and security.

Database & RedisCopy Anchor Link

Redis handles session caching, application cache, and queued background tasks. Ensure your .env contains:

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

Test that Redis is responding:

redis-cli ping
# Response should be PONG

Mail ConfigurationCopy Anchor Link

Aquadactyl needs email configuration to send password resets and account notifications. Under Admin → Settings → Mail, choose SMTP, Mailgun, Postmark or Amazon SES, enter the selected service's settings and send a test email. Provider credentials are encrypted when saved in the panel. Database-backed mail settings require APP_ENVIRONMENT_ONLY=false.

See Email services for the supported options. To configure SMTP through the environment instead, use:

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS[email protected]
MAIL_FROM_NAME="Aquadactyl Panel"

After modifying .env, clear configuration cache:

cd /var/www/aquadactyl
sudo -u www-data php artisan config:clear
sudo -u www-data php artisan cache:clear

Blueprint Extension FrameworkCopy Anchor Link

Aquadactyl includes Blueprint beta-2026-08 built-in. Blueprint allows you to install community themes, custom dashboard widgets, and feature addons.

Using the Blueprint CLICopy Anchor Link

The Blueprint command-line interface is available in the panel root:

cd /var/www/aquadactyl
sudo blueprint -version

Installing an ExtensionCopy Anchor Link

1. Place the myextension.blueprint package in your panel root directory (/var/www/aquadactyl/).
2. Run the installation command:

cd /var/www/aquadactyl
sudo blueprint -i myextension

The CLI patches templates, installs dependencies using pnpm, and runs database migrations.

Reapplying PermissionsCopy Anchor Link

Installing extensions can change file ownership. Reapply deployment permissions after modifying extensions:

curl -fsSL https://raw.githubusercontent.com/Aquadactyl/Installer/main/deploy.sh | sudo bash -s -- permissions

Background Worker (aquaq.service)Copy Anchor Link

Background tasks like server creation, backups, and email delivery run through the aquaq.service worker.

Aquadactyl includes the production unit definition at deploy/systemd/aquaq.service:

[Unit]
Description=Aquadactyl queue worker
After=network-online.target mariadb.service redis-server.service
Wants=network-online.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/aquadactyl
ExecStart=/usr/bin/php artisan queue:work --queue=high,standard,low --sleep=3 --tries=3 --timeout=120 --max-time=3600
Restart=always
RestartSec=5
TimeoutStopSec=180
KillSignal=SIGTERM
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo cp deploy/systemd/aquaq.service /etc/systemd/system/aquaq.service
sudo systemctl daemon-reload
sudo systemctl enable --now aquaq.service

Cron SchedulerCopy Anchor Link

Install the Laravel task scheduler to run scheduled tasks and automated backups:

echo "* * * * * www-data cd /var/www/aquadactyl && /usr/bin/php artisan schedule:run >> /dev/null 2>&1" | sudo tee /etc/cron.d/aquadactyl

Firewall Setup (UFW)Copy Anchor Link

Protect your panel by only exposing necessary ports:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP (Let's Encrypt / Redirect)
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable