diff --git a/CHANGELOG.md b/docs/CHANGELOG.md similarity index 100% rename from CHANGELOG.md rename to docs/CHANGELOG.md diff --git a/docs/UPDATE-NITROV3.md b/docs/UPDATE-NITROV3.md new file mode 100644 index 0000000..e4bc6ea --- /dev/null +++ b/docs/UPDATE-NITROV3.md @@ -0,0 +1,402 @@ +# Update-NitroV3.sh — Guide & Troubleshooting + +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 + ```