Native Update Guide

Guide for updating your native Hydrodactyl installation and resolving common issues

Updating Your Native Installation

Newest release version:

Before proceeding with any updates, make sure to back up your database and panel files. Provided below is how you can make a backup of your Panel Database. (Replace panel with the database name you use)

# If using MySQL
mysqldump -u root -p --opt panel > ./panel.sql

# If using MariaDB
mariadb-dump -u root -p --opt panel > ./panel.sql

Prerequisites

Root or sudo access on your server
Latest NodeJS LTS installed
Composer installed globally
Backup of your current installation

Update Steps

Install a Node Version Manager:

curl -o- https://fnm.vercel.app/install | bash

Install Node 22:
```
fnm install 22
```
Navigate to your Hydrodactyl installation directory:
```
cd /path/to/your/hydrodactyl
```

Download the latest release:

curl -L https://github.com/blueprintframework/hydrodactyl/releases/latest/download/panel.tar.gz | tar -xzv

Enable maintenance mode:
```
php artisan down
```
Set proper permissions:
```
chmod -R 755 storage/* bootstrap/cache
```

Install PHP dependencies:

composer install --no-dev --optimize-autoloader

Clear application cache:

php artisan view:clear
php artisan config:clear

Run database migrations:
```
php artisan migrate --seed --force
```

Set ownership based on your web server:

# For NGINX (non-CentOS)
chown -R www-data:www-data /var/www/pterodactyl/*

# For NGINX (CentOS)
chown -R nginx:nginx /var/www/pterodactyl/*

# For Apache (CentOS)
chown -R apache:apache /var/www/pterodactyl/*

Restart the queue worker:
```
php artisan queue:restart
```

Install and build frontend assets:

npm install -g corepack@latest
corepack enable pnpm
pnpm i --frozen-lockfile && pnpm run ship

Verify permissions:
```
chmod -R 755 storage/* bootstrap/cache/
```
Disable maintenance mode:
```
php artisan up
```

Troubleshooting Common Issues

Hydration Mismatch Errors

If you encounter hydration mismatch errors in the browser console, try these steps:

Clear your browser cache and cookies

Rebuild the frontend assets:

pnpm i --frozen-lockfile && pnpm run ship

Clear the application cache:

php artisan view:clear
php artisan config:clear

Hydration mismatches often occur when the server-rendered content doesn't match the client-side rendered content. This can happen due to browser extensions or cached assets.

Permission Issues

If you encounter permission issues after updating:

Verify the ownership of your files matches your web server user

Ensure storage and cache directories are writable:

chmod -R 755 storage/* bootstrap/cache/
chown -R www-data:www-data storage bootstrap/cache

Replace www-data with your web server user (nginx, apache) if different.