chat/docs/FASTPANEL_MANUAL_FRONTEND.md

Manual frontend installation on VPS with FastPanel

This guide is for the safe mode where FastPanel manages domains, SSL certificates, and web server configs manually through its UI.

The project must not create domains, edit FastPanel virtual hosts, or restart the web stack automatically.

Goal

FastPanel UI:
- create domains
- enable SSL
- choose web root directories
- configure api reverse proxy if needed

Project scripts:
- build admin-panel
- build widget
- copy static files only into selected web roots

Recommended domains

Choose domains manually in FastPanel, for example:

admin.example.ru   -> admin panel
widget.example.ru  -> embeddable widget
api.example.ru     -> reverse proxy to Raspberry Pi backend

All DNS A-records should point to the VPS IP:

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

Step 1. Create sites in FastPanel manually

In FastPanel:

1. Create website admin.example.ru
2. Create website widget.example.ru
3. Create website api.example.ru
4. Enable Let's Encrypt SSL for each domain
5. Check that each site opens in browser

Do not configure this through project scripts.

Step 2. Find web root paths

FastPanel usually stores website files here:

/var/www/<fastpanel-user>/data/www/<domain>

Examples:

/var/www/siteuser/data/www/admin.example.ru
/var/www/siteuser/data/www/widget.example.ru

Confirm exact paths in FastPanel before configuring deploy.

Step 3. Build frontend locally on VPS

SSH into VPS:

cd /opt/raspi-chat/source
git pull --ff-only origin main
npm install
npm run build:admin
npm run build:widget

Expected output directories:

admin-panel/dist
widget/dist

Step 4. Copy admin panel files manually

Replace siteuser and domains with your real FastPanel user/domain paths.

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

Step 5. Copy widget files manually

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

Important safety rule:

Use --delete only inside the exact domain web root.
Never run rsync --delete against /var/www, /var/www/<user>, or /var/www/<user>/data/www.

Step 6. Manual widget embed code

After publishing widget files, use:

<script
  src="https://widget.example.ru/widget.js"
  data-site-id="site_xxxxx"
  data-api-url="https://api.example.ru">
</script>

Step 7. Manual API reverse proxy

The api.example.ru domain should proxy traffic to Raspberry Pi backend through WireGuard.

Target:

http://10.8.0.2:3000

Configure this through FastPanel custom Nginx settings if available.

Required behavior:

https://api.example.ru/health -> http://10.8.0.2:3000/health
https://api.example.ru/api/*  -> http://10.8.0.2:3000/api/*
wss://api.example.ru/ws       -> http://10.8.0.2:3000/ws

Typical Nginx custom directives:

location /ws {
    proxy_pass http://10.8.0.2: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://10.8.0.2: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;
}

Before any reload:

sudo nginx -t

Reload only if FastPanel/custom config requires it:

sudo systemctl reload nginx

Step 8. Disable automatic frontend deploy if manual mode is preferred

In backend/deploy settings use:

FRONTEND_DEPLOY_ENABLED=false
FRONTEND_DEPLOY_MODE=manual-fastpanel

In this mode, the admin panel can show deployment instructions and current version, but it must not run deployment commands.

Recommended manual update flow

cd /opt/raspi-chat/source
git pull --ff-only origin main
npm install
npm run build:admin
npm run build:widget
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 checklist

Before copying files:

pwd
ls admin-panel/dist
ls widget/dist

Check target paths:

ls /var/www/siteuser/data/www/admin.example.ru
ls /var/www/siteuser/data/www/widget.example.ru

Never run:

rm -rf /var/www/*
rsync --delete something/ /var/www/
systemctl restart nginx

Manual FastPanel mode is the safest option for a VPS where other production websites are already running.