chat/docs/VPS_ONLY_INSTALL.md

VPS-only installation with FastPanel

This is the current MVP architecture.

Raspberry Pi is not used for the MVP backend. Everything runs on the VPS where FastPanel is already installed.

Architecture

VPS with FastPanel
  ├── admin.example.ru   -> static admin panel
  ├── widget.example.ru  -> static embeddable widget
  ├── api.example.ru     -> reverse proxy to local backend
  ├── Node.js backend    -> 127.0.0.1:3000
  ├── SQLite database    -> /opt/raspi-chat/data/chat.sqlite
  └── Telegram bot       -> backend process

FastPanel rule

Create domains/sites manually in FastPanel. The project must not create sites, overwrite FastPanel configs, or restart the whole web stack.

Create manually:

admin.example.ru
widget.example.ru
api.example.ru

Enable SSL manually in FastPanel for all three domains.

DNS

All records point to the VPS IP:

admin.example.ru   A  VPS_IP
widget.example.ru  A  VPS_IP
api.example.ru     A  VPS_IP

Project directories

/opt/raspi-chat/
  source/     # git clone
  data/       # SQLite database
  logs/       # logs
  backups/    # backups before updates
  updates/    # future update bundles

FastPanel webroots remain separate:

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

Do not publish files into api.example.ru. It is proxy-only.

Install packages on VPS

sudo apt update
sudo apt upgrade -y
sudo apt install -y git curl rsync sqlite3 ca-certificates gnupg build-essential python3 make g++

Install Node.js

Recommended for Ubuntu 24.04 VPS:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm -v

Install PM2

sudo npm install -g pm2
pm2 -v

Clone project

sudo mkdir -p /opt/raspi-chat
sudo chown -R $USER:$USER /opt/raspi-chat
cd /opt/raspi-chat
git clone https://github.com/viktor138irk/chat.git source
cd source
npm install

Configure backend

cp backend/.env.example backend/.env
nano backend/.env

Minimum VPS-only values:

APP_ENV=production
APP_HOST=127.0.0.1
APP_PORT=3000
PUBLIC_API_URL=https://api.example.ru
PUBLIC_WS_URL=wss://api.example.ru/ws
TRUST_PROXY=true
DATABASE_PATH=/opt/raspi-chat/data/chat.sqlite
ADMIN_ORIGIN=https://admin.example.ru
WIDGET_ORIGIN=https://widget.example.ru
TELEGRAM_BOT_TOKEN=
JWT_SECRET=change-me-to-long-random-string

Create data directory:

mkdir -p /opt/raspi-chat/data /opt/raspi-chat/logs /opt/raspi-chat/backups /opt/raspi-chat/updates

Start backend

Manual test:

npm run dev:backend

Health check:

curl http://127.0.0.1:3000/health

Expected:

{"ok":true,"service":"raspi-chat-backend","env":"production"}

Production with PM2:

pm2 start backend/src/server.js --name raspi-chat-backend
pm2 save
pm2 startup

Run the command printed by pm2 startup.

Configure api.example.ru proxy in FastPanel

Use FastPanel custom Nginx directives if available.

Target:

http://127.0.0.1:3000

Typical config:

location /ws {
    proxy_pass http://127.0.0.1:3000/ws;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

If editing any Nginx config manually, always run:

sudo nginx -t

Reload only if needed:

sudo systemctl reload nginx

Build admin and widget

cd /opt/raspi-chat/source
npm run build:admin
npm run build:widget

Publish admin and widget manually

Replace siteuser with the real FastPanel user.

rsync -av --delete admin-panel/dist/ /var/www/siteuser/data/www/admin.example.ru/
rsync -av --delete widget/dist/ /var/www/siteuser/data/www/widget.example.ru/

Safety rule:

Use --delete only inside exact domain webroot directories.
Never use rsync --delete against /var/www or parent folders.

Public checks

curl https://api.example.ru/health

Open in browser:

https://admin.example.ru
https://widget.example.ru

Future updater in admin panel

The admin panel will include an updater section, but sites/domains are still managed manually in FastPanel.

Updater should support:

- check current version
- upload/apply update bundle
- update backend source
- build admin/widget
- publish static files to configured webroots
- restart PM2 backend
- show logs
- rollback static files/backend source later

MVP starts with manual mode:

FRONTEND_DEPLOY_ENABLED=false
FRONTEND_DEPLOY_MODE=manual-fastpanel