diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..6c214ed --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,348 @@ +# Installation guide + +This guide describes the MVP deployment model: + +```text +VPS with FastPanel + - admin panel static files + - widget static files + - public api.example.ru reverse proxy + - WireGuard server + +Raspberry Pi 3B at home + - backend API + - WebSocket + - Telegram bot + - SQLite database + - WireGuard client +``` + +Cloudflare is not required. + +## 1. Required domains + +Create DNS A-records pointing to the VPS IP: + +```text +admin.example.ru -> VPS_IP +widget.example.ru -> VPS_IP +api.example.ru -> VPS_IP +``` + +## 2. FastPanel setup on VPS + +Create three sites in FastPanel: + +```text +admin.example.ru +widget.example.ru +api.example.ru +``` + +Enable HTTPS for all three domains using FastPanel/Let's Encrypt. + +Expected static webroots: + +```text +/var/www//data/www/admin.example.ru +/var/www//data/www/widget.example.ru +``` + +Do not manually overwrite FastPanel generated configs. + +## 3. VPS base packages + +```bash +sudo apt update +sudo apt upgrade -y +sudo apt install -y git curl rsync wireguard +``` + +Install Node.js 20 LTS on VPS. + +Example using NodeSource: + +```bash +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt install -y nodejs +node -v +npm -v +``` + +## 4. Clone project on VPS + +```bash +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 +``` + +## 5. Configure frontend deploy agent + +```bash +cp deploy/deploy-agent/.env.example deploy/deploy-agent/.env +nano deploy/deploy-agent/.env +``` + +Example: + +```env +FRONTEND_DEPLOY_BRANCH=main +FRONTEND_DEPLOY_SOURCE_PATH=/opt/raspi-chat/source +FRONTEND_DEPLOY_ADMIN_WEBROOT=/var/www/example_user/data/www/admin.example.ru +FRONTEND_DEPLOY_WIDGET_WEBROOT=/var/www/example_user/data/www/widget.example.ru +FASTPANEL_SAFE_MODE=true +``` + +Run first frontend deploy: + +```bash +npm run deploy:frontend +``` + +This builds and publishes: + +```text +admin-panel -> admin.example.ru +widget -> widget.example.ru +``` + +## 6. Raspberry Pi OS + +Recommended for Raspberry Pi 3B: + +```text +Raspberry Pi OS Lite 32-bit +``` + +Install base packages: + +```bash +sudo apt update +sudo apt upgrade -y +sudo apt install -y git curl sqlite3 ufw fail2ban wireguard rsync +``` + +Install Node.js 20 LTS if available. If memory is tight, Node.js 18 LTS is acceptable for MVP. + +```bash +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt install -y nodejs +node -v +npm -v +``` + +## 7. Clone project on Raspberry Pi + +```bash +mkdir -p ~/apps +cd ~/apps +git clone https://github.com/viktor138irk/chat.git +cd chat +npm install +``` + +## 8. Configure backend on Raspberry Pi + +```bash +cp backend/.env.example backend/.env +nano backend/.env +``` + +Example: + +```env +APP_ENV=production +APP_HOST=0.0.0.0 +APP_PORT=3000 +PUBLIC_API_URL=https://api.example.ru +PUBLIC_WS_URL=wss://api.example.ru/ws +TRUST_PROXY=true + +DATABASE_PATH=./data/chat.sqlite + +ADMIN_ORIGIN=https://admin.example.ru +WIDGET_ORIGIN=https://widget.example.ru + +TELEGRAM_BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN +TELEGRAM_PROXY_ENABLED=false +TELEGRAM_PROXY_TYPE=socks5 +TELEGRAM_PROXY_HOST=127.0.0.1 +TELEGRAM_PROXY_PORT=9050 +TELEGRAM_PROXY_USERNAME= +TELEGRAM_PROXY_PASSWORD= + +JWT_SECRET=change-me-to-long-random-string +``` + +Create data directory: + +```bash +mkdir -p backend/data +``` + +## 9. Run backend manually + +```bash +npm run dev:backend +``` + +Health check from Raspberry Pi: + +```bash +curl http://127.0.0.1:3000/health +``` + +Expected response: + +```json +{"ok":true,"service":"raspi-chat-backend","env":"production"} +``` + +## 10. Run backend with PM2 + +```bash +sudo npm install -g pm2 +pm2 start backend/src/server.js --name raspi-chat-backend +pm2 save +pm2 startup +``` + +Follow the command printed by `pm2 startup`. + +Useful commands: + +```bash +pm2 status +pm2 logs raspi-chat-backend +pm2 restart raspi-chat-backend +``` + +## 11. WireGuard network + +Recommended VPN network: + +```text +VPS: 10.8.0.1 +Raspberry Pi: 10.8.0.2 +``` + +After WireGuard is configured, VPS should reach backend: + +```bash +curl http://10.8.0.2:3000/health +``` + +## 12. FastPanel API reverse proxy + +For `api.example.ru`, configure reverse proxy to Raspberry Pi through WireGuard: + +```text +http://10.8.0.2:3000 +``` + +Required paths: + +```text +/api/* -> http://10.8.0.2:3000/api/* +/health -> http://10.8.0.2:3000/health +/ws -> http://10.8.0.2:3000/ws with WebSocket upgrade +``` + +Use FastPanel UI/custom Nginx directives if available. Do not overwrite FastPanel generated configs manually. + +Typical Nginx location for WebSocket: + +```nginx +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; +} +``` + +Typical Nginx location for API: + +```nginx +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 reload: + +```bash +sudo nginx -t +``` + +Reload only if needed: + +```bash +sudo systemctl reload nginx +``` + +## 13. Test public API + +From your computer: + +```bash +curl https://api.example.ru/health +``` + +Expected: + +```json +{"ok":true,"service":"raspi-chat-backend","env":"production"} +``` + +## 14. Widget embed code + +Use this on any website: + +```html + +``` + +Later the production build will expose a stable widget file path, for example: + +```html + +``` + +## 15. Current MVP status + +Implemented: + +- backend health endpoint +- widget message endpoint +- WebSocket endpoint +- React admin shell +- embeddable widget shell +- FastPanel-safe deploy agent + +Next implementation step: + +- SQLite schema +- message persistence +- Telegram forwarding +- reply mapping from Telegram back to website