170 lines
5.3 KiB
Markdown
170 lines
5.3 KiB
Markdown
# 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.
|