upating_unit3d_version/upating_unit3d_version.md

UNIT3D Update

Whether you're upgrading from UNIT3D v8.3.3 to v9.0.1 or updating your PHP environment from 8.3 to 8.4, this tutorial offers a detailed guide to the entire process.

[!IMPORTANT]
backup.

Prerequisites

• Complete backup in ~/tempBackup
• Sudo privileges
• Current versions:
  • UNIT3D: v8.3.3
  • PHP: 8.3
• Required tools:

  curl, apt, nginx, mysql/mariadb, nano/micro
  

1. Create a Backup

UNIT3D provides built-in backup tools through PHP Artisan.

2. Update Procedures

2.1 Enter Maintenance Mode & Prepare Meilisearch

cd /var/www/html
php artisan down

Meilisearch Update:

sudo apt update
sudo apt upgrade
sudo systemctl stop meilisearch
sudo curl -L https://install.meilisearch.com | sudo sh
sudo mv ./meilisearch /usr/local/bin/
sudo chmod +x /usr/local/bin/meilisearch
sudo rm -rf /var/lib/meilisearch/data

Proceed with the following command:

Note: This step had to be repeated.

sudo chmod +x /usr/local/bin/meilisearch
sudo systemctl start meilisearch

2.2 Update PHP to 8.4

Add PHP Repository & Update Package Lists:

sudo add-apt-repository ppa:ondrej/php
sudo apt update

Backup Current PHP Packages & Install PHP 8.4:

sudo dpkg -l | grep php | tee ~/tempBackup/packages.txt
sudo apt install php8.4-common php8.4-cli php8.4-fpm php8.4-{redis,bcmath,curl,dev,gd,igbinary,intl,mbstring,mysql,opcache,readline,xml,zip}

2.3 NGINX Configuration Update

Edit Nginx configuration file:

sudo nano /etc/nginx/sites-available/default

Update the fastcgi_pass directive to use the PHP 8.4 socket:

Note:
Locate the line

fastcgi_pass unix:/var/run/php/***.sock;

and replace *** with your site’s identifier.

For example, to point to the PHP 8.4 FPM socket:

fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;

Save and exit the editor.

Test the Nginx configuration:

sudo nginx -t

Restart Nginx and PHP-FPM, and Remove PHP 8.3:

sudo nginx -t
sudo systemctl restart nginx
sudo systemctl restart php8.4-fpm 
sudo systemctl stop php8.3-fpm
sudo apt purge '^php8.3.*'
php -v

3. Update UNIT3D

cd /var/www/html
php artisan git:update

During the update process, UNIT3D differences all files and prompts the user to choose whether to keep the current version or update to the new one; typically, it is recommended to update all files, but before beginning the update, the most recent backup should be copied to ~/tempBackup, and after the update, the list of file conflicts is saved as ~/tempBackup/fileConflicts.txt so that, once the process is complete, these files can be reviewed to determine which changes should be merged or discarded.

4. Database Migration Fix

During the update, you might encounter an error related to the tickets table

2025_02_17_074140_update_columns_to_boolean ......................................................................................... 38.50ms FAIL

In Connection.php line 825:                                                                                                              
  SQLSTATE[22004]: Null value not allowed: 1138 Invalid use of NULL value (Connection: mysql, SQL: alter table `tickets` modify `staff_read` tinyint(1) not null default '0')                                                                                                                 

In Connection.php line 571:                     
  SQLSTATE[22004]: Null value not allowed: 1138 Invalid use of NULL value

Resolve NULL values in tickets table:

1. Log in to MySQL:

mysql -u your_username -p

When prompted, enter your MySQL password. Once logged in, select the appropriate database by running:

USE your_database_name;

1. Fix the Null Values:

Run the following SQL command to update any null entries in the staff_read column to 0:

UPDATE tickets SET staff_read = 0 WHERE staff_read IS NULL;

9. Exit MySQL:

exit;

2. Complete migrations:

php artisan migrate

---

5. Final Reset & Cleanup

After updating and migrating, run the following commands to clear caches, reinstall dependencies, rebuild assets, and restart services:

sudo -u www-data composer install --prefer-dist --no-dev -o && \
sudo php artisan cache:clear && \
sudo php artisan queue:clear && \
sudo php artisan auto:email-blacklist-update && \
sudo php artisan auto:cache_random_media && \
sudo php artisan set:all_cache && \
bun install && \
bun run build && \
sudo php artisan migrate && \
sudo systemctl restart php8.4-fpm && \
sudo php artisan queue:restart && \
sudo supervisorctl reread && \
sudo supervisorctl update && \
sudo supervisorctl reload && \
sudo php artisan scout:sync-index-settings && \
sudo php artisan auto:sync_torrents_to_meilisearch --wipe && \
sudo php artisan auto:sync_people_to_meilisearch

Finally, finish the update and bring your site back online:

sudo php artisan scout:sync-index-settings && \
sudo php artisan auto:sync_torrents_to_meilisearch --wipe && \
sudo php artisan auto:sync_people_to_meilisearch && \
sudo php artisan set:all_cache && \
sudo systemctl restart php8.4-fpm && \
sudo php artisan queue:restart && \
sudo php artisan up