feat: add production deployment and runtime safeguards

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-28 15:48:44 -03:00
parent 8ce2fcdfea
commit a9ef4d776d
23 changed files with 1696 additions and 8 deletions
@@ -0,0 +1,169 @@
+# Docker Cloud 24/7 Design
+
+## Goal
+
+Run Maquina Comercial Pessoal continuously in a free cloud environment with Docker, persistent data, safe WhatsApp recovery, and Telegram alerts when manual action is required.
+
+## Chosen Approach
+
+Use Oracle Cloud Always Free with an Ubuntu VM, Docker Compose, persistent volume storage, Caddy for HTTPS, and Telegram Bot API alerts.
+
+This is the best free option because Oracle Always Free can provide an always-on VM and persistent block volume. Other free platforms may sleep or restart unpredictably, which is risky for a WhatsApp Web session and scheduled campaign windows.
+
+## Runtime Architecture
+
+- One Ubuntu VM on Oracle Cloud Always Free.
+- Docker Engine and Docker Compose installed on the VM.
+- One application container running `npm start`.
+- One Caddy container acting as reverse proxy and HTTPS terminator.
+- Persistent host directory or block volume mounted into the app container.
+- Telegram alerts sent directly from the app using Bot API HTTPS requests.
+
+## Required Application Changes
+
+### Network Binding
+
+The server currently listens on `127.0.0.1`. In Docker it must support binding to `0.0.0.0`.
+
+Add `APP_HOST`, defaulting to `127.0.0.1` for local safety. In Docker set `APP_HOST=0.0.0.0`.
+
+### Persistent Paths
+
+The following paths must survive container restarts and image updates:
+
+- SQLite database: `data/maquina-pessoal.db`
+- WhatsApp auth/session: `data/runtime/whatsapp-auth`
+- Exports: `data/exports`
+- Any runtime logs or backups
+
+Use a single mounted volume at `/app/data` and configure:
+
+- `APP_DB_PATH=/app/data/maquina-pessoal.db`
+- `APP_WHATSAPP_AUTH_DIR=/app/data/runtime/whatsapp-auth`
+
+### Health Endpoint
+
+Add or reuse a lightweight HTTP health endpoint suitable for Docker healthcheck and uptime checks.
+
+The endpoint must not leak secrets. It can expose:
+
+- app status
+- database open/migrated
+- WhatsApp state summary
+- campaign scheduler state summary
+
+### Telegram Alerts
+
+Add Telegram configuration:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_CHAT_ID`
+- `TELEGRAM_ALERTS_ENABLED=true|false`
+
+Use Telegram Bot API `sendMessage` over HTTPS.
+
+Send alerts for:
+
+- WhatsApp leaves `READY` after previously being ready.
+- WhatsApp enters `QR_REQUIRED`.
+- Initial reconnect fails on startup.
+- Campaigns are paused by `server_restart`.
+- Worker sees repeated send errors above a safe threshold.
+
+Alerts must be deduplicated to avoid spam. Use a cooldown window per alert key, for example 15 minutes.
+
+### Restart Semantics
+
+Keep the current safe behavior: campaigns pause after server restart. This prevents blind sending after container or VM restarts.
+
+When this happens, Telegram should notify the operator to review and resume manually.
+
+## Docker Files
+
+### Dockerfile
+
+Use Node 24, install production dependencies, copy app files, expose the app port, and run `npm start`.
+
+Do not bake secrets into the image.
+
+### docker-compose.yml
+
+Services:
+
+- `app`
+  - build from local Dockerfile
+  - `restart: unless-stopped`
+  - `env_file: .env.production`
+  - mount persistent `./data:/app/data`
+  - expose app port only to the internal Docker network
+  - healthcheck hitting the app health endpoint
+
+- `caddy`
+  - official Caddy image
+  - `restart: unless-stopped`
+  - ports `80:80` and `443:443`
+  - Caddyfile mounted read-only
+  - Caddy data/config volumes persisted
+
+## HTTPS and Access
+
+Preferred: use a domain pointed to the VM public IP and let Caddy issue Let's Encrypt certificates.
+
+If no domain is available, HTTP by IP can work temporarily but is not recommended for a login panel.
+
+The app already has authentication. The production admin password must be changed from the default before exposing the panel.
+
+## Oracle Cloud Setup
+
+- Create Always Free Ubuntu VM.
+- Attach or use persistent boot/block volume within Always Free limits.
+- Install Docker and Docker Compose plugin.
+- Open OCI security list/NSG for ports `80` and `443` only.
+- Restrict SSH to the operator IP when possible.
+- Clone/copy the project to the VM.
+- Create `.env.production` with production values.
+- Run `docker compose up -d --build`.
+
+## Backup Plan
+
+Create a daily SQLite backup job on the host or in a sidecar/script.
+
+Backup target:
+
+- `/app/data/backups/maquina-pessoal-YYYY-MM-DD.zip`
+
+Retain the last 7 to 14 backups to control storage usage.
+
+The backup must include at least:
+
+- SQLite database
+- WhatsApp auth directory
+
+## Safety Rules
+
+- Do not send messages automatically after an app/container restart.
+- Do not expose Telegram token in logs.
+- Do not commit `.env.production`.
+- Do not use the real WhatsApp provider in tests.
+- Do not remove existing manual approval gates.
+- Keep campaign resume a deliberate operator action after Telegram alert.
+
+## Verification
+
+Before production deployment:
+
+- `npm test`
+- `npm run test:browser` if browsers are available
+- `npm audit --omit=dev`
+- Docker build succeeds
+- Container healthcheck becomes healthy
+- Telegram test alert is received
+- App can show QR and reconnect WhatsApp
+- Data persists after `docker compose restart`
+- Campaign pause after restart triggers Telegram alert
+
+## Open Operational Requirements
+
+- Operator must create a Telegram bot with BotFather.
+- Operator must provide `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` locally on the VM.
+- Operator should decide whether to use a domain for HTTPS. HTTPS with a domain is recommended before exposing the panel.