diff --git a/upating_unit3d_version.md b/upating_unit3d_version.md index 3ce3df6..296107b 100644 --- a/upating_unit3d_version.md +++ b/upating_unit3d_version.md @@ -1,203 +1,97 @@ # Updating UNIT3D -This guide walks you through updating UNIT3D from `v8.3.3` to `v9.0.1` and upgrading PHP from `8.3` to `8.4`. +Update UNIT3D to the latest version by reviewing the release notes and following the steps below: + +## 1. Create Backup + +UNIT3D offers built-in backups. Refer to the Backups documentation for usage. > [!IMPORTANT] -> Ensure you have a complete backup before proceeding. +> Ensure a complete backup is on hand before proceeding. -## 1. Prerequisites +## 2. Enter Maintenance Mode -- **Backup** located in `~/tempBackup` -- **Sudo** privileges. -- **Current versions**: - - `UNIT3D`: `v8.3.3` - - `PHP`: `8.3` -- **Tools**: - ```text - curl, apt, nginx, mysql/mariadb, nano - ``` - -## 2. Create Backup - -UNIT3D offers built-in backups. Refer to the Backups page in this wiki for usage. - -> [!IMPORTANT] -> Verify your backups before continuing. - -## 3. Enter Maintenance Mode - -```bash +```sh cd /var/www/html php artisan down ``` -## 4. Update Meilisearch - -```bash -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. - -```bash -sudo chmod +x /usr/local/bin/meilisearch -sudo systemctl start meilisearch -``` - -### 2.2 Update PHP to 8.4 - -Add PHP Repository & Update Package Lists: - -```bash -sudo add-apt-repository ppa:ondrej/php -sudo apt update -``` - -Backup Current PHP Packages & Install PHP 8.4: - -```bash -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:** - -```bash -sudo nano /etc/nginx/sites-available/default -``` - -#### **Update the `fastcgi_pass` directive to use the PHP 8.4 socket:** - -> **Note:** -> Locate the line -> ```nginx -> 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: - -```nginx -fastcgi_pass unix:/var/run/php/php8.4-fpm.sock; -``` - -Save and exit the editor. - -#### **Test the Nginx configuration:** - -```bash -sudo nginx -t -``` - -#### **Restart Nginx and PHP-FPM, and Remove PHP 8.3:** - -```bash -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 -```bash +Proceed to update UNIT3D: + +Copy the latest backup to `~/tempBackup` before starting. + + +```sh 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 - -```sql -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 +php artisan git:update 2>&1 | tee ~/tempBackup/updateLogs.txt ``` -**Resolve NULL values in tickets table:** +During the update, UNIT3D prompts for action on file differences. It is suggested to accept the updated files. After the update, review `~/tempBackup/updateLogs.txt` for conflicts. Any modifications will need to be re-implemented with the new code. + -1. Log in to MySQL: +### *[PLACEHOLDER]* + Fill in process for successful update steps here, migration y/n, and possibly another. -```bash -mysql -u your_username -p -``` +## 4. Resume Site Functionality -When prompted, enter your MySQL password. Once logged in, select the appropriate database by running: +On a successful update process; clear the cache, restart the PHP-FPM service, restart the Laravel queues, and finally bring the site live. -```bash -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: - -```sql -UPDATE tickets SET staff_read = 0 WHERE staff_read IS NULL; -``` - -9. Exit MySQL: - -```sql -exit; -``` - -2. Complete migrations: -```bash -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:** - -```bash -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:** -```bash -sudo php artisan scout:sync-index-settings && \ -sudo php artisan auto:sync_torrents_to_meilisearch --wipe && \ -sudo php artisan auto:sync_people_to_meilisearch && \ +```sh sudo php artisan set:all_cache && \ sudo systemctl restart php8.4-fpm && \ sudo php artisan queue:restart && \ sudo php artisan up ``` +> [!TIP] +> If running external Unit3d-Announce, restart the supervisor services. + +```sh +sudo supervisorctl reread && \ +sudo supervisorctl update && \ +sudo supervisorctl reload +``` +--- + + +## Troubleshooting Clean-up + +During the update, an error related to a migration is a common occurance. It is important to review the error being described and make changes accordingly to clear any issues with the data at hand. + +The below list of commands to finish a complete update process: + +Finish any migrations not completed: +`sudo php artisan migrate` + +Reinstall dependencies: +`sudo -u www-data composer install --prefer-dist --no-dev -o` + +Clear caches: +```sh +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 +``` +Rebuild static assets: +`bun install && bun run build` + +Restart the PHP-FPM service: +`sudo systemctl restart php8.4-fpm` + +Restart the Laravel queues: +`sudo php artisan queue:restart` + +Bring the site live: +`sudo php artisan up` + +> [!TIP] +> If running external Unit3d-Announce, restart the supervisor services. + +```sh +sudo supervisorctl reread && \ +sudo supervisorctl update && \ +sudo supervisorctl reload +```