Installing the Panel
Complete step-by-step manual installation guide for Aquadactyl Panel on a Linux server without running the automated installer script.
This guide walks you through manually installing Aquadactyl Panel step-by-step without using the automated installer script.
Looking for a fast automated install? See the Automated Install guide to install in minutes using the standalone deployment script.
System Requirements
Before starting, ensure your server meets the following requirements:
| Component | Minimum / Supported Specification |
|---|---|
| Operating System | Ubuntu: 24.04 LTS, 24.10, 26.04+ LTSDebian: 12 (Bookworm), 13 (Trixie) |
| PHP | PHP 8.5 (recommended) or PHP 8.4 with PHP-FPM via Ondřej Surý repo (PHP 8.2 & 8.3 unsupported) |
| PHP Extensions | bcmath, curl, gd, intl, mbstring, pdo_mysql, posix, redis, xml, zip |
| Node.js & pnpm | Node.js 24 (via NVM v0.40.8 with npm@latest) and pnpm 12.10.1 (pinned) |
| Composer | Composer 2 |
| Database & Cache | MariaDB 10.11+ / MySQL 8.0+ and Redis 6+ |
| System Tools | rsync, util-linux (flock, runuser), zip, unzip, git, curl, mariadb-client / mysqldump |
| Hardware | 2+ CPU Cores, 2 GB RAM, 20+ GB SSD/NVMe |
Deprecation Notice: Debian ≤ 11 and Ubuntu ≤ 22.04 are deprecated and no longer supported. Please upgrade to Ubuntu 24.04+ or Debian 12+ before installing Aquadactyl.
Step 1: Install System Packages
To configure the needed packages, update your system and install the required dependencies:
sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y lsb-release ca-certificates curl apt-transport-https gnupg
# Add Sury PHP repository
curl -sSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb
rm -f /tmp/debsuryorg-archive-keyring.deb
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/debsuryorg-archive-keyring.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" > /etc/apt/sources.list.d/php.list'
sudo apt-get update
# Install PHP 8.5 and required extensions
sudo apt-get install -y php8.5 php8.5-cli php8.5-fpm php8.5-gd php8.5-mysql php8.5-mbstring \
php8.5-bcmath php8.5-xml php8.5-curl php8.5-zip php8.5-posix php8.5-intl php8.5-redis \
mariadb-server mariadb-client nginx redis-server git tar zip unzip rsync util-linux certbot python3-certbot-nginx
# Install Composer 2
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer
# Install Node.js 24 & pinned pnpm 12.10.1 via NVM v0.40.8
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 24
nvm use 24
npm install --global npm@latest
npm install --global [email protected]Step 2: Configure MariaDB Database
Open your database shell:
sudo mariadb -u rootCreate the database and grant permissions:
CREATE DATABASE aquadactyl;
CREATE USER 'aquadactyl'@'127.0.0.1' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON aquadactyl.* TO 'aquadactyl'@'127.0.0.1' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EXIT;Step 3: Download Panel Code
Create the panel directory and clone the Aquadactyl repository:
sudo mkdir -p /var/www/aquadactyl
cd /var/www/aquadactyl
sudo git clone https://github.com/Aquadactyl/aquadactyl.git .Step 4: Configure Environment
Copy the example environment file and set secure permissions:
sudo cp .env.example .env
sudo chmod 640 .env
sudo nano .envConfigure your domain name and credentials:
APP_URL=https://panel.example.com
DB_HOST=127.0.0.1
DB_DATABASE=aquadactyl
DB_USERNAME=aquadactyl
DB_PASSWORD=your_secure_password
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redisStep 5: Install Dependencies
Install Composer PHP packages and Node frontend dependencies using the frozen lockfiles:
cd /var/www/aquadactyl
# Install PHP dependencies
sudo COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader
# Install Node dependencies
sudo pnpm install --frozen-lockfileStep 6: Generate Encryption Keys
Generate the Laravel application key and configure Hashids salt in .env:
sudo php artisan key:generate --forceIf HASHIDS_SALT is empty in .env, generate a 32-character random string and add it:
sudo sed -i "s/^HASHIDS_SALT=.*$/HASHIDS_SALT=$(openssl rand -hex 16)/" .envStep 7: Database Migrations & Seeders
Run the database migrations and seed the bundled Blueprint framework tables:
sudo php artisan migrate --force
sudo php artisan db:seed --class=BlueprintSeeder --force
# Seed default nests & eggs for game servers
sudo php artisan db:seed --class=DatabaseSeeder --forceStep 8: Initialize Blueprint & Build Frontend
Initialize the bundled Blueprint beta-2026-08 integration and compile the production frontend:
# Initialize Blueprint
sudo BLUEPRINT_ENVIRONMENT=ci bash blueprint.sh
sudo php artisan bp:cache
# Build production assets
sudo pnpm run buildStep 9: Configure File Permissions
Set the strict production permissions model (code owned by root:www-data, only storage/ and bootstrap/cache/ writable by www-data):
cd /var/www/aquadactyl
sudo chown -R root:www-data /var/www/aquadactyl
# Restore executable flags for tools and scripts
sudo chmod 0750 blueprint.sh
# Writable application state 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 chmod 0640 .envYou can also restore strict permissions automatically at any time using: curl -fsSL https://raw.githubusercontent.com/Aquadactyl/Installer/main/deploy.sh | sudo bash -s -- permissions
Step 10: Create Initial Administrator
Create your administrative user:
sudo -u www-data php artisan p:user:makeFollow the interactive prompts to enter your email address, username, first name, last name, and password.
Step 11: Cache Configuration & Optimize
Cache Laravel configuration, routes, and views:
sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo -u www-data php artisan view:cacheNext Steps
Complete your installation by configuring the web server and background queue worker:
- Webserver Configuration — Set up Nginx or Caddy with SSL.
- Additional Configuration — Configure the background queue worker (
aquaq.service), cron scheduler, and Redis.