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:

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:

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

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

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

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

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

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.

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

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.

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

sudo apt install mariadb-client

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

grep NITRO_DB_ .env

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

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:

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.

sudo apt install maven

Java version mismatch

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.

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

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

---

5.5 yarn install fails

"yarn: command not found"

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

Node version too low

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:

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"

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

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

"JavaScript heap out of memory"

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

Vite version conflict

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

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

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.

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

pm2 restart all

If you use Docker compose:

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.

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:

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:

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:

  screen -S update
  bash update-Nitrov3.sh
  # Ctrl+A D to detach, screen -r update to reattach