Operations and observability

Live financial movement remains disabled. Monitor the actual services and durable queues independently of the public interface.

Service health

/healthz checks API responsiveness and /readyz checks PostgreSQL. The web container checks its /pt page. Run the worker separately from web and API; it processes durable webhook, provider-notification and email queues. Monitor failed jobs, expired leases and growing pending queues. An SMTP uncertain outcome requires review rather than a blind resend.

Metrics and history

GET /v1/metrics requires metrics:read and returns only the authenticated business's records:

• receivedBrlCents: integer BRL cents confirmed received on live payments, not the requested amount.
• settledUsdt: an exact decimal string for confirmed live USDT settlement.
• settledCount: number of confirmed live USDT settlements.
• sandboxPaymentCount: separate count of sandbox payments.
• auditEventCount: count of business audit records.

Keep BRL and USDT separate. Do not convert settledUsdt to binary floating point for financial arithmetic, and do not interpret these cumulative totals as a custodial balance.

The dashboard uses a separate overview endpoint with a selected environment and UTC calendar-day period. A receipt or settlement falls in the period of its confirmation, even when the payment was requested earlier. GET /v1/requests exposes recent sanitized method, route, status, duration and correlation metadata without bodies, secret headers or query strings. Audit history records relevant actor and resource actions. There is no public infrastructure-status service or external alerting integration included.

Recovery

• Quote source failure: use configured fallback sources; never serve expired prices.
• Worker failure: restart the worker; expired leases allow another instance to resume.
• Repeated notification: deduplicate before applying any payment transition.
• Unknown provider outcome: reconcile without issuing another charge.
• Exposed credential: revoke or replace it and review relevant activity.
• Application rollback: use the previous release's pinned image manifest; see deployment.

Release monitoring

The GitHub Actions workflow verifies the revision before deploying main through a forced SSH command. Check the verification and deployment job results, the server's REVISION and /opt/magnum/shared/deployed-commit, container health and the public HTTPS response. A green verification job alone does not prove deployment succeeded; a skipped stale revision also does not mean that revision was published.

The server serializes deployments with /opt/magnum/shared/deploy.lock, uses read-only repository access, builds four images pinned to the commit SHA and runs the backup hook before migration. /opt/magnum/current advances only after application and public health checks succeed. If startup or public health fails, the prior pinned application images are restored while the database remains at its migrated version. Review the deploy result and repeat health checks after any automatic rollback.

A manual rollback must use the previous release's compose.images.yaml and restart only api, worker and web with --no-build --no-deps. Never replay an old deployment SHA through the forced command: it accepts only the current origin/main. Preserve database backups and verify migration compatibility before restoring old application images. See deployment for the exact command and GitHub secret names.

Rotation and retention

Changing API_KEY_PEPPER invalidates current keys. Replacing ENCRYPTION_KEY without re-encryption makes old fields unreadable. Plan versioned secret migration with backups. The operator alone manages the global FOUR_P_API_KEY; changing it does not grant provider approval or enable live payments.

Establish external alerts, recovery objectives, data-retention windows and a tested off-host restore before production financial use. Compose is a deployment foundation, not a high-availability guarantee.