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.

1. Create a Backup

UNIT3D provides built-in backup tools through PHP Artisan.

2. Table of Contents

• Prerequisites
• Update Procedures
  • 4.1 Enter Maintenance Mode & Prepare Meilisearch
  • 4.2 Update PHP to 8.4
  • 4.3 Update UNIT3D
  • 4.4 Database Migration Fix
• Post-Update Procedures
• Troubleshooting

---

3. 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
  

---

4. Update Procedures

4.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

4.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}

NGINX Configuration Update:

1. Edit Nginx configuration file::

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

2. 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.

3. Test the Nginx configuration:

sudo nginx -t

4. 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

4.3 Update UNIT3D

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

[!NOTE]
During file conflicts:

• Backup conflicts to ~/tempBackup/fileConflicts.txt
• Generally recommend accepting all updates
• After the update, it's a good idea to save any file conflicts for review

4.4 Database Migration Fix

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

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. Post-Update Procedures

Final System Reset:

sudo -u www-data composer install --prefer-dist --no-dev -o
sudo php artisan set:all_cache
bun install && bun run build
sudo systemctl restart php8.4-fpm
sudo supervisorctl reload

Meilisearch Reindexing:

sudo php artisan scout:sync-index-settings
sudo php artisan auto:sync_torrents_to_meilisearch --wipe
sudo php artisan auto:sync_people_to_meilisearch

Bring System Online:

php artisan up

---

6. Troubleshooting

Common Issues:

• Migration Errors: Ensure database user has ALTER privileges
• PHP Version Mismatch: Verify php -v and NGINX config
• Meilisearch Failures: Check /var/log/meilisearch.log

Log Locations:

/var/www/html/storage/logs/laravel.log
/var/log/nginx/error.log