Updating the Panel

Aquadactyl supports two ways to update your panel and bundled Blueprint: a step-by-step manual update executing each command directly from your terminal, or an automated update using the standalone deployment script (deploy.sh from Aquadactyl/Installer).

Both approaches preserve existing configurations, extension database state, and user storage, while reapplying active Blueprint extensions and compiling production frontend assets.

Manual Update (Step-by-Step)Copy Anchor Link

Follow these step-by-step instructions to manually update your Aquadactyl Panel installation without running the automated deployment script.

Step 1: Maintenance Mode & Stop Queue WorkerCopy Anchor Link

Place the panel into maintenance mode so users cannot make modifications during the upgrade, and stop the background queue worker so jobs are not processed against changing code or databases:

cd /var/www/aquadactyl

# Put panel into maintenance mode
sudo -u www-data php artisan down --retry=60

# Stop the background queue worker
sudo systemctl stop aquaq.service

Step 2: Create BackupsCopy Anchor Link

Always take a snapshot of both your database and your current panel directory before making changes:

# Create backup directory outside the web root
sudo mkdir -p /var/backups/aquadactyl
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Backup the database
sudo php /var/www/aquadactyl/artisan p:maintenance:backup-database /var/backups/aquadactyl/database-${TIMESTAMP}.sql
# Or alternatively via mariadb-dump / mysqldump:
# sudo mariadb-dump -u aquadactyl -p aquadactyl > /var/backups/aquadactyl/database-${TIMESTAMP}.sql

# Backup existing panel files (excluding node_modules and transient caches)
sudo tar -czf /var/backups/aquadactyl/panel-${TIMESTAMP}.tar.gz \
  --exclude='./node_modules' \
  --exclude='./.git' \
  --exclude='./storage/logs/*.log' \
  --exclude='./storage/framework/cache/data/*' \
  -C /var/www/aquadactyl .

Step 3: Download & Extract Release FilesCopy Anchor Link

Download the new panel.tar.gz release archive and extract it over your existing installation.

# Specify target release tag (e.g. v0.2.0)
RELEASE_TAG="vRELEASE_TAG"

# Download release archive and checksums
curl -L -o /tmp/panel.tar.gz "https://github.com/Aquadactyl/aquadactyl/releases/download/${RELEASE_TAG}/panel.tar.gz"
curl -L -o /tmp/SHA256SUMS "https://github.com/Aquadactyl/aquadactyl/releases/download/${RELEASE_TAG}/SHA256SUMS"

# Verify SHA256 checksum
cd /tmp && sha256sum --check --ignore-missing SHA256SUMS

# Extract archive to a temporary directory
mkdir -p /tmp/aquadactyl-update
tar -xzf /tmp/panel.tar.gz -C /tmp/aquadactyl-update

# Synchronize release files into panel root while preserving data and configuration
sudo rsync -av --no-owner --no-group \
  --exclude='.env' \
  --exclude='.blueprintrc' \
  --exclude='storage/' \
  --exclude='bootstrap/cache/' \
  --exclude='.blueprint/dev/' \
  --exclude='.blueprint/tmp/' \
  --exclude='.blueprint/extensions/blueprint/private/db/' \
  --exclude='.blueprint/extensions/blueprint/private/debug/' \
  /tmp/aquadactyl-update/ /var/www/aquadactyl/

# Clean up temporary archive files
rm -rf /tmp/aquadactyl-update /tmp/panel.tar.gz /tmp/SHA256SUMS

Step 4: Update DependenciesCopy Anchor Link

Clear cached manifests, then install the updated PHP packages via Composer and Node dependencies via pinned pnpm:

cd /var/www/aquadactyl

# Clear stale cached manifests
sudo rm -f bootstrap/cache/{config,packages,services,events,routes-v7}.php

# Install locked PHP Composer packages
sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --prefer-dist --no-interaction --no-scripts --optimize-autoloader

# Install locked Node dependencies (using pinned pnpm)
sudo pnpm install --frozen-lockfile

# Discover Laravel packages
sudo php artisan package:discover --ansi

Step 5: Database Migrations & SeedersCopy Anchor Link

Apply database schema changes and run the bundled Blueprint database seeders:

cd /var/www/aquadactyl

sudo php artisan migrate --force
sudo php artisan db:seed --class=BlueprintSeeder --force

Step 6: Initialize Blueprint & Reapply ExtensionsCopy Anchor Link

Re-initialize the bundled Blueprint integration:

cd /var/www/aquadactyl

# Ensure blueprint.sh is executable
sudo chmod 0750 blueprint.sh

# Re-initialize Blueprint
sudo BLUEPRINT_ENVIRONMENT=ci bash blueprint.sh
sudo php artisan bp:cache

If you have installed Blueprint extensions (stored in .blueprint/extensions/blueprint/private/db/installed_extensions), reapply each extension package to re-inject hooks, views, and routes into the new source code:

# For each installed extension, re-run installation to regenerate code hooks:
sudo bash blueprint.sh -bash -i path/to/myextension.blueprint

Step 7: Build Production Frontend AssetsCopy Anchor Link

Compile the updated frontend assets:

cd /var/www/aquadactyl
sudo pnpm run build

Step 8: Configure Permissions & Warm CachesCopy Anchor Link

Apply the strict least-privilege permission structure (root:www-data ownership for code, writable only for storage/ and bootstrap/cache/) and warm the Laravel cache:

cd /var/www/aquadactyl

# Set code ownership and script execution permissions
sudo chown -R root:www-data /var/www/aquadactyl
sudo chmod 0750 blueprint.sh artisan

# Set permissions for writable directories
sudo mkdir -p storage/framework/{cache/data,sessions,views} storage/logs bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache
sudo find storage bootstrap/cache -type d -exec chmod 0750 {} +
sudo find storage bootstrap/cache -type f -exec chmod 0640 {} +
sudo chmod 0640 .env

# Warm configuration, route, and view caches
sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo -u www-data php artisan view:cache

Step 9: Restart Services & Bring Panel OnlineCopy Anchor Link

Reload PHP-FPM, restart the queue worker, and bring the panel out of maintenance mode:

# Reload PHP-FPM (adjust version if using php8.4-fpm)
sudo systemctl reload php8.5-fpm

# Start background queue worker
sudo systemctl start aquaq.service
sudo -u www-data php /var/www/aquadactyl/artisan queue:restart

# Bring the panel back online
sudo -u www-data php /var/www/aquadactyl/artisan up

Managed Update Script (Automated)Copy Anchor Link

If you prefer an automated upgrade, Aquadactyl provides a managed update routine via deploy.sh that automates all the steps above, including checksum verification, pre-flight checks, automatic backups, and extension reapplication.

You can execute the update directly using the one-liner:

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

Or if deploy.sh is already present on your server:

sudo bash deploy.sh update vRELEASE_TAG

Replace vRELEASE_TAG with a valid release tag beginning with v (e.g. v0.2.0).

Updating from a Downloaded ArchiveCopy Anchor Link

If you have already downloaded panel.tar.gz and reviewed its SHA256 checksum:

sudo bash deploy.sh update --archive /tmp/panel.tar.gz YOUR_64_CHARACTER_SHA256

What the Update Script AutomatesCopy Anchor Link

1. Pre-flight & Checksum Verification: Validates the operating system and SHA256 checksum of panel.tar.gz against SHA256SUMS, checking for directory traversal or unsafe archive paths.
2. Blueprint Extension Validation: Reads all installed extensions from .blueprint/extensions/blueprint/private/db/installed_extensions and ensures every corresponding myextension.blueprint package is present in the panel directory before touching any files.
3. Queue Pause & Maintenance Mode: Stops aquaq.service to halt asynchronous background writes and puts the panel into maintenance mode (artisan down --retry=60).
4. Automated Private Backups: Creates a secure, timestamped backup directory in /var/backups/aquadactyl/ (mode 0700) containing:
   • database.sql: Full database snapshot taken via php artisan p:maintenance:backup-database.
   • panel.tar.gz: Complete archive of the existing panel directory (excluding .git and node_modules).
5. Safe File Extraction: Extracts the release archive via rsync, preserving .env, .blueprintrc, storage/, bootstrap/cache/, and extension state directories.
6. Locked Dependency Reinstallation: Runs composer install and pnpm install --frozen-lockfile using the committed lockfiles.
7. Database Migrations & Blueprint Seeder: Applies any schema changes (artisan migrate --force) and seeds Blueprint's database tables (BlueprintSeeder).
8. Extension Re-application: Re-initializes Blueprint and executes bash blueprint.sh -bash -i "$extension" for every installed extension to regenerate hooks into the new source code.
9. Production Asset Compilation: Compiles frontend assets with pnpm run build.
10. Cache Generation & Service Reload: Refreshes configuration, route, and view caches, reloads PHP-FPM, restarts aquaq.service, and brings the panel back online (artisan up).

Restoring From a Failed UpdateCopy Anchor Link

If an update fails at any step, maintenance mode remains enabled and the queue remains stopped. The script prints the path to the backup created in /var/backups/aquadactyl/ (e.g. /var/backups/aquadactyl/20261008T160000Z-abc123/).

To recover your previous version:

1. Stop PHP-FPM and the queue worker:

   Copy Text

   sudo systemctl stop php8.5-fpm aquaq.service

2. Move the failed panel directory aside and recreate the original path:

   Copy Text

   sudo mv /var/www/aquadactyl /var/www/aquadactyl-failed
   sudo mkdir -p /var/www/aquadactyl

3. Extract the filesystem backup:

   Copy Text

   sudo tar -xzf /var/backups/aquadactyl/TIMESTAMP-XXXXXX/panel.tar.gz -C /var/www/aquadactyl

4. Restore the database snapshot:

   Copy Text

   sudo mariadb -u aquadactyl -p aquadactyl < /var/backups/aquadactyl/TIMESTAMP-XXXXXX/database.sql

5. Reapply permissions, clear caches, and restart services:

   Copy Text

   curl -fsSL https://raw.githubusercontent.com/Aquadactyl/Installer/main/deploy.sh | sudo bash -s -- permissions
   sudo systemctl start php8.5-fpm aquaq.service
   sudo -u www-data php /var/www/aquadactyl/artisan up