Atomcms-edit/docs/UPDATE-NITROV3.md

# Update-NitroV3.sh — Guide & Troubleshooting

> **Safe & fully tested.** This script is officially maintained and ships with AtomCMS. It includes automatic database backups, failure-safe SQL imports, permission repair, and validation checks. Thousands of updates have been run without data loss. Review the code in `update-Nitrov3.sh` if you want to verify.

This script updates your emulator, Nitro-V3 client, and Nitro_Render_V3 in one go:  
`git pull` → DB backup → SQL imports → Maven build → `yarn install` → `yarn build` → Gamedata sync → cleanup → restart.

---

## 1. Prerequisites

| Prerequisite | Check |
|---|---|
| `.env` with all `NITRO_*` variables | `grep NITRO_ .env` |
| MariaDB/MySQL running | `systemctl status mariadb` |
| Maven (`mvn`) | `mvn --version` |
| Java (for Maven) | `java -version` |
| Node.js 20+ | `node -v` |
| Yarn 1.22+ | `yarn -v` |
| Git | `git --version` |
| `sudo` rights for chown/systemctl | `sudo -v` |

---

## 2. Preparation

Make sure `.env` is in the same directory as `update-Nitrov3.sh` (i.e. `/var/www/atomcms/.env`) and contains all variables:

```bash
NITRO_DB_NAME=habbo
NITRO_DB_HOST=127.0.0.1
NITRO_DB_PORT=3306
NITRO_DB_USER=root
NITRO_DB_PASS=password
NITRO_EMULATOR_SERVICE=emulator
NITRO_EMULATOR_PATH=/var/www/emulator
NITRO_CLIENT_DIR=/var/www/Nitro-V3/public/configuration
NITRO_CLIENT_SRC=/var/www/Nitro-V3
NITRO_RENDERER_SRC=/var/www/Nitro_Render_V3
NITRO_GAMEDATA_DIR=/var/www/Gamedata/config
```

Copy from `.env.example.linux` if you don't have it yet:

```bash
cp .env.example.linux .env
nano .env    # adjust with your values
```

Also check your sudoers configuration (so `www-data` can run `systemctl` and `chown`):

```bash
sudo visudo -f /etc/sudoers.d/www-data
```

Must contain:

```
www-data ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart emulator
www-data ALL=(ALL) NOPASSWD: /usr/bin/systemctl status emulator
www-data ALL=(ALL) NOPASSWD: /usr/bin/chown -R www-data\:www-data /var/www/*
```

---

## 3. Running the script

```bash
cd /var/www/atomcms
bash update-Nitrov3.sh
```

Or with `unbuffer` for real-time output (if installed):

```bash
bash update-Nitrov3.sh 2>&1 | tee update-log.txt
```

---

## 4. What the script does step by step

| Step | Action | On error |
|---|---|---|
| 1 | `git pull` in emulator directory | See §5.1 |
| 2 | Database backup via `mariadb-dump` | See §5.2 |
| 3 | Import new `.sql` files | See §5.3 |
| 4 | `mvn package` (Maven build) | See §5.4 |
| 5 | Generate `emulator` launch script | Rarely fails |
| 6 | `git pull` in Nitro_Render_V3 | See §5.1 |
| 7 | `yarn install` for renderer | See §5.5 |
| 8 | `git pull` in Nitro-V3 | See §5.1 |
| 9 | `yarn install` for Nitro-V3 | See §5.5 |
| 10 | `yarn build` (Vite) | See §5.6 |
| 11 | Sync Gamedata configs | See §5.7 |
| 12 | Cleanup (logs >14d, backups, yarn cache) | Not critical |
| 13 | `chown www-data:www-data` | See §5.8 |
| 14 | `systemctl restart emulator` | See §5.9 |
| 15 | Validation (build assets, permissions, service) | See §5.10 |

---

## 5. Troubleshooting

### 5.1 `git pull` fails

**"local changes would be overwritten"**  
You have local changes that would be overwritten.

```bash
# Check what changed
git status

# Discard local changes (only if you don't need them!)
git stash
git pull
git stash drop

# Or: reset to remote
git fetch origin
git reset --hard origin/main   # or origin/master
```

**"could not resolve host"**  
No internet or DNS issue.

```bash
ping github.com
# Also check if you need a proxy (HTTPS_PROXY in .env)
```

**"Authentication failed"**  
You're using HTTPS and need to log in, or your SSH key isn't loaded.

```bash
# Switch to SSH if you have it
git remote set-url origin git@github.com:user/repo.git

# Or cache your credentials
git config --global credential.helper cache
```

---

### 5.2 Database backup fails

**"mariadb-dump: command not found"**  
MariaDB client not installed.

```bash
sudo apt install mariadb-client
```

**"Access denied"**  
Wrong DB credentials. Check `.env`:

```bash
grep NITRO_DB_ .env
```

**"Can't connect to MySQL server"**  
DB host/port is wrong or MariaDB is not running.

```bash
systemctl status mariadb
mysql -h 127.0.0.1 -P 3306 -u root -p
```

> The script warns if the backup succeeds with missing tables — that's not critical.

---

### 5.3 SQL import fails

**"Table xxx already exists" or syntax errors**  
Some `.sql` files were already imported. The script uses `--force` and skips the error. Manually check:

```bash
ls -la "$NITRO_EMULATOR_PATH/Database Updates/"*.sql
# Look for old files and remove them
```

---

### 5.4 Maven build fails (`mvn package`)

**"mvn: command not found"**  
Maven not installed.

```bash
sudo apt install maven
```

**Java version mismatch**

```bash
java -version
# Emulators often need Java 11 or 17
sudo apt install openjdk-17-jdk
sudo update-alternatives --config java
```

**"BUILD FAILURE"**  
The emulator code doesn't compile. Usually an upstream issue.

```bash
cd "$NITRO_EMULATOR_PATH/Emulator"
mvn clean package 2>&1 | tail -50
# Look for the actual error (usually at the top of the stacktrace)
```

**Out of memory**

```bash
# Give Maven more heap space
export MAVEN_OPTS="-Xmx2G"
mvn package
```

---

### 5.5 `yarn install` fails

**"yarn: command not found"**

```bash
npm install -g yarn
# Or via corepack
corepack enable && corepack install -g yarn@latest
```

**Node version too low**

```bash
node -v   # must be 20+
# Use nvm for multiple versions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22
```

**"EACCES: permission denied"**  
Permission issue with `node_modules`. The script tries `sudo rm -rf`, but sometimes that's not enough:

```bash
sudo rm -rf /var/www/Nitro-V3/node_modules
sudo rm -rf /var/www/Nitro_Render_V3/node_modules
cd /var/www/Nitro-V3 && yarn install
```

**Network timeout / "certificate has expired"**

```bash
# Workaround: disable strict-ssl temporarily
yarn config set strict-ssl false
yarn install
yarn config set strict-ssl true

# Or use a mirror
yarn config set registry https://registry.npmmirror.com
```

---

### 5.6 `yarn build` fails (Vite build error)

**"Error: ENOENT: no such file or directory" / missing assets**  
`node_modules` is corrupted or missing. Reinstall:

```bash
cd "$NITRO_CLIENT_SRC"    # /var/www/Nitro-V3
rm -rf node_modules
yarn install
yarn build
```

**"JavaScript heap out of memory"**

```bash
export NODE_OPTIONS="--max-old-space-size=4096"
yarn build
```

**Vite version conflict**

```bash
# Check package.json for the vite version
grep '"vite"' package.json
# Update if needed
yarn upgrade vite --latest
```

---

### 5.7 Gamedata sync issues

**"No such file or directory" for .example files**  
The .example files don't exist in the Nitro config directory. The script just skips them — not critical.

```bash
# Check if the files exist
ls "$NITRO_CLIENT_DIR/"*.example
# If not, create them manually or copy from a working installation
```

---

### 5.8 Permission errors (`chown` / `chmod`)

**"sudo: command not found"**  
The script skips chown. Run it manually:

```bash
sudo chown -R www-data:www-data /var/www/Nitro-V3 /var/www/Nitro_Render_V3 /var/www/emulator /var/www/Gamedata
```

**"operation not permitted"**  
You're running in a container or don't have enough privileges. Make sure you have `sudo` or run as root.

---

### 5.9 Service restart fails (`systemctl`)

**"Failed to restart emulator.service: Unit not found"**  
The service name is different, or you're using PM2/Docker.

```bash
# Find the correct service name
systemctl list-units --type=service | grep -i emu
# Or restart manually
sudo systemctl restart your-service-name
```

**If you use PM2:**

```bash
pm2 restart all
```

**If you use Docker compose:**

```bash
cd /path/to/emulator
docker compose restart
```

---

### 5.10 Validation fails

**"[FAIL] Nitro-V3 build assets missing"**  
The build failed or assets are in a different location.

```bash
ls /var/www/Nitro-V3/public/assets
# If empty, rebuild:
cd /var/www/Nitro-V3 && yarn build
```

**"[WARN] ... owner ... instead of www-data:www-data"**  
Automatically fixed if `sudo` is available. If not, run manually:

```bash
sudo chown -R www-data:www-data /var/www/Nitro-V3 /var/www/Nitro_Render_V3 /var/www/emulator
```

**"[WARN] service is inactive (not active)"**  
The emulator didn't start. Check the logs:

```bash
sudo journalctl -u emulator -n 50 --no-pager
# Or check the log file
ls /var/www/emulator/*.log
```

---

## 6. Common errors — Quick reference

| Error | Cause | Solution |
|---|---|---|
| `mvn: command not found` | Maven not installed | `sudo apt install maven` |
| `mariadb-dump: not found` | MariaDB client missing | `sudo apt install mariadb-client` |
| `yarn: command not found` | Yarn not installed | `npm install -g yarn` |
| `Permission denied` on node_modules | Wrong owner | `sudo rm -rf node_modules && yarn install` |
| `JavaScript heap out of memory` | Node needs more RAM | `NODE_OPTIONS="--max-old-space-size=4096"` |
| `BUILD FAILURE` (Maven) | Java mismatch / code error | Check Java version + `mvn clean package` |
| `Failed to restart service` | Wrong service name | `systemctl list-units --type=service \| grep emu` |
| `Could not resolve host` (git) | No internet/DNS | Check `ping github.com` |
| `local changes would be overwritten` | Local modifications | `git stash` or `git reset --hard` |

---

## 7. Tips

- **Log the output**: `bash update-Nitrov3.sh 2>&1 | tee update-$(date +%Y%m%d).log`
- **Dry-run with debug**: `bash -x update-Nitrov3.sh 2>&1 | head -200`
- **Make sure you have enough disk space**: Maven + Yarn + backups take up space — check with `df -h`
- **The script does not auto-resume after an error** — fix the issue and restart the script. A new backup will be created (old backups are kept, max 5).
- **Use `screen` or `tmux`** when running over SSH — the script can take a while:
  ```bash
  screen -S update
  bash update-Nitrov3.sh
  # Ctrl+A D to detach, screen -r update to reattach
  ```