COMERCIAL-GTI/maquina-comercial-pessoal/docs/superpowers/specs/2026-08-03-docker-cloud-247-design.md

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.