# 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:
  ```text
  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

```bash
cd /var/www/html
php artisan down
```

**Meilisearch Update:**
```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
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
```

**Resolve NULL values in tickets table:**

1. Log in to MySQL:

```bash
mysql -u your_username -p
```

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

```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 && \
sudo php artisan set:all_cache && \
sudo systemctl restart php8.4-fpm && \
sudo php artisan queue:restart && \
sudo php artisan up
```