Native Installation

The guide for migration has moved to a new page.

For Hydrodactyl-specific issues, join our Discord community at https://discord.gg/sK686yHdaK for support.

Windows is currently only supported for development purposes.

Prerequisites

Linux system with root access
php 8.4
pnpm
git
curl
Mariadb, Mysql, or Postgresql
Redis
composer v2

Installing Composer

Composer is a dependency manager for PHP. It's required to operate the panel.
This might be different depending on what operating system you are one. For the most part though it should just be

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Downloading the Panel

This process is also quite straight-forward.

mkdir -p /var/www/hydrodactyl
cd /var/www/hydrodactyl

curl -Lo panel.tar.gz https://github.com/blueprintframework/hydrodactyl/releases/latest/download/panel.tar.gz
tar -xzvf panel.tar.gz
chmod -R 755 storage/* bootstrap/cache/

Installing the panel

  cp .env.example .env
  COMPOSER_ALLOW_SUPERUSER=1 composer install --no-dev --optimize-autoloader

If you don't have enough ram on your server to complete the build. you can account for this by activating swap!

  pnpm build

Only run the command below if you are installing this Panel for the first time and do not have any Hydrodactyl Panel data in the database.

php artisan key:generate --force

Back up your encryption key (APP_KEY in the .env file). It is used as an encryption key for all data that needs to be stored securely (e.g. API keys). Store it somewhere safe - not just on your server. If you lose it, all encrypted data is irrecoverable, even with database backups.

To grab your APP_KEY, open a terminal and run the following in your panel directory:

  grep APP_KEY /var/www/hydrodactyl/.env

Save this somewhere safe, as you'll need it to recover data should that need arise.

Environment Configuration

Hydrodactyl's core environment is easily configured using a few different CLI commands built into the app. This step will cover setting up things such as sessions, caching, database credentials, and email sending.

  php artisan p:environment:setup
  php artisan p:environment:database

  # To use PHP's internal mail sending (not recommended), select "mail". To use a
  # custom SMTP server, select "smtp".
  php artisan p:environment:mail

Database Setup

php artisan migrate --seed --force

Add The First User

You'll then need to create an administrative user so that you can log into the panel. To do so, run the command below. At this time passwords must meet the following requirements: 8 characters, mixed case, at least one number.

php artisan p:user:make

Set Permissions

  # If using NGINX, Apache or Caddy (not on RHEL / Rocky Linux / AlmaLinux)
  chown -R www-data:www-data /var/www/hydrodactyl/*

  # If using NGINX on RHEL / Rocky Linux / AlmaLinux
  chown -R nginx:nginx /var/www/hydrodactyl/*

  # If using Apache on RHEL / Rocky Linux / AlmaLinux
  chown -R apache:apache /var/www/hydrodactyl/*

Queue Listeners

Crontab Configuration

The first thing we need to do is create a new cronjob that runs every minute to process specific Hydrodactyl tasks, such as session cleanup and sending scheduled tasks to daemons. You'll want to open your crontab using sudo crontab -e and then paste the line below.

  * * * * * php /var/www/hydrodactyl/artisan schedule:run >> /dev/null 2>&1

Create Queue Worker

Next you need to create a new systemd worker to keep our queue process running in the background. This queue is responsible for sending emails and handling many other background tasks for Hydrodactyl. Create a file called pyroq.service in /etc/systemd/system with the contents below.

  # /etc/systemd/system/pyroq.service
  # Hydrodactyl Queue Worker File
  # ----------------------------------

  [Unit]
  Description=Hydrodactyl Queue Worker
  After=redis-server.service

  [Service]
  # On some systems the user and group might be different.
  # Some systems use `apache` or `nginx` as the user and group.
  User=www-data
  Group=www-data
  Restart=always
  ExecStart=/usr/bin/php /var/www/hydrodactyl/artisan queue:work --queue=high,standard,low --sleep=3 --tries=3
  StartLimitInterval=180
  StartLimitBurst=30
  RestartSec=5s

  [Install]
  WantedBy=multi-user.target

Redis on RHEL / Rocky Linux / AlmaLinux

If you are using RHEL, Rocky Linux, or AlmaLinux, you will need to replace redis-server.service with redis.service at the After= line in order to ensure redis starts before the queue worker.

If you are not using redis for anything you should remove the After= line, otherwise you will encounter errors when the service starts.

If you are using redis for your system, you will want to make sure to enable that it will start on boot. You can do that by running the following command:

sudo systemctl enable --now redis-server

Finally, enable the service and set it to boot on machine start.

sudo systemctl enable --now pyroq.service

Telemetry

Hydrodactyl Collects No data what-so ever. This might change to anonymous in the future to facilitate faster updates, and quicker bug fixes.