You've already forked Atomcms-edit
Move CHANGELOG to docs/ and add English update-NitroV3 tutorial with troubleshooting
This commit is contained in:
root
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user