chat/docs/UPDATE_BUNDLE.md

Update bundle workflow

This project can be updated manually by copying an update bundle to the VPS and running a controlled updater script.

The VPS has FastPanel, so updates must not manage domains or global web server configs.

Goal

The assistant can prepare a versioned update bundle file. The user uploads it to the VPS. The updater applies updates to:

• admin panel static files
• widget static files
• backend/API source on Raspberry Pi or deployment instructions for Raspberry Pi
• docs/config templates

Recommended VPS directory layout

Use one project directory on VPS:

/opt/raspi-chat/
  source/              # git clone or unpacked project source
  updates/             # uploaded update bundles
  backups/             # previous static builds/config backups
  logs/                # updater logs
  build/               # temporary build output

FastPanel still owns public website directories:

/var/www/<fastpanel-user>/data/www/admin.example.ru
/var/www/<fastpanel-user>/data/www/widget.example.ru

The API subdomain is not a static directory. It should be a reverse proxy:

api.example.ru -> VPS FastPanel/Nginx -> WireGuard -> Raspberry Pi backend

One project directory, three subdomains

Recommended mapping:

admin.example.ru
  public files from /opt/raspi-chat/source/admin-panel/dist
  copied to /var/www/<user>/data/www/admin.example.ru

widget.example.ru
  public files from /opt/raspi-chat/source/widget/dist
  copied to /var/www/<user>/data/www/widget.example.ru

api.example.ru
  no static deploy
  reverse proxy to http://10.8.0.2:3000

If FastPanel forces every subdomain to have a webroot, create one for api.example.ru, but do not publish project files there. Configure it as proxy-only where possible.

Update bundle format

Preferred bundle name:

raspi-chat-update-YYYYMMDD-HHMMSS.tar.gz

Preferred structure inside bundle:

manifest.json
source/
  package.json
  backend/
  admin-panel/
  widget/
  deploy/
  docs/
scripts/
  apply-update.sh

Example manifest.json:

{
  "project": "raspi-chat",
  "version": "0.1.0",
  "commit": "unknown",
  "requires": {
    "node": ">=20",
    "fastpanelSafeMode": true
  },
  "targets": {
    "admin": true,
    "widget": true,
    "api": true
  }
}

Manual updater flow on VPS

1. Upload bundle to /opt/raspi-chat/updates
2. Extract bundle into temporary directory
3. Validate manifest
4. Backup current admin/widget webroots
5. Build admin-panel
6. Build widget
7. Copy static files into FastPanel webroots
8. Do not touch FastPanel global configs
9. Print API/backend update notes

API/backend updates

The backend runs on Raspberry Pi, not on the FastPanel VPS. Therefore API updates have two safe modes:

Mode A: Git pull on Raspberry Pi

cd ~/apps/chat
git pull --ff-only origin main
npm install
pm2 restart raspi-chat-backend

Mode B: update bundle for Raspberry Pi

Copy backend files from the update bundle to Raspberry Pi and restart PM2.

Recommended Raspberry Pi path:

~/apps/chat

FastPanel-safe rule

The updater may write only to:

/opt/raspi-chat/source
/opt/raspi-chat/updates
/opt/raspi-chat/backups
/opt/raspi-chat/logs
/var/www/<fastpanel-user>/data/www/admin.example.ru
/var/www/<fastpanel-user>/data/www/widget.example.ru

The updater must not write to:

/etc/nginx
/etc/apache2
/usr/local/fastpanel2
/var/www
/var/www/<fastpanel-user>
/var/www/<fastpanel-user>/data/www

Future admin button

When manual updates are stable, the admin panel can get a button:

Upload update bundle
Validate bundle
Apply frontend update
Show backend update instructions

For MVP, manual terminal execution is safer.