RedditBot/docs/deployment.md

# Deployment and operations

## Production model

The production unit is the `reddit-bot` Docker Compose service. The image uses the Playwright base, installs/builds the Node application, serves the compiled React dashboard and Express API on port 3000, and stores state under `/app/data` on the named `reddit_bot_data` volume.

The container does not run VNC, accept Reddit passwords, or scrape a Matrix token from a login browser. Account authentication enters through a locally exported session dump and is persisted in the sensitive volume.

## Authority and safety

Deployment, restart, start/resume, session import, configuration mutation, send actions, and data deletion are separate operations. Only perform the ones the user explicitly requested. In particular, “commit and push” does not authorize a Dokploy deployment or bot restart.

Before any live operation:

1. Confirm the target is the RedditBot Compose service, not the whole Dokploy host/instance.
2. Inspect current Git revision, worktree/remote state, deployment state, bot running/paused state, account runtimes, and recent errors.
3. Identify whether the action can send messages or change account state.
4. Back up affected persistent state before destructive or migration-heavy work.
5. Define observable success criteria and a recovery path.

## Required environment

The Compose service passes:

- `OPENROUTER_API_KEY`;
- `WEB_DASHBOARD_TOKEN`;
- optional `REDDIT_BOT_AGENT_READ_TOKEN`;
- optional `REDDIT_BOT_AGENT_CONTROL_TOKEN`.

Dokploy access credentials are stored in the ignored repository `.env`. Use them only when access is explicitly requested. Never print the file, include tokens in commands that will be echoed, commit them, or copy response metadata containing credentials. Follow redirects for Dokploy API calls.

## Persistence

`reddit_bot_data:/app/data` contains:

- SQLite database and WAL files;
- imported browser/account sessions;
- cached Matrix credentials/state;
- downloaded private media;
- per-account browser profiles.

A volume replacement or deletion is therefore a destructive account-and-content reset. Verify a readable backup before touching it and state exactly what will be lost. Removing a Compose application and deleting its volume are not the same action.

## Deployment procedure

Use the actual current Dokploy API/Compose identifiers from a read-only lookup; do not copy identifiers into documentation or assume an older deployment still has the same ID.

1. Confirm the intended commit exists on the tracked remote branch.
2. Read current Compose/deployment status and capture the prior image/revision if available.
3. Confirm whether the bot must remain paused through deployment. Do not change persisted running state unless authorized.
4. Trigger the bounded Compose deployment.
5. Poll the deployment record to a terminal success/failure state; an accepted trigger is not completion.
6. Verify the running container is the new deployment and is not restarting.
7. Verify public `GET /healthz` and authenticated `GET /api/v1/readyz`/overview as appropriate.
8. Verify account runtime count/state, bot paused/running state, sync/cooldown state, and recent sanitized logs.
9. Verify the persistent volume is mounted and pre-deployment data is readable.

Do not use a green container health badge as the only evidence. The process may be healthy while account runtimes are logged out, the bot is paused, Matrix is degraded, or candidate/reply work is blocked.

## Health semantics

- `/healthz`: unauthenticated process liveness only; intentionally reveals no private state.
- `/api/v1/readyz`: authenticated component readiness and degraded authentication state.
- `/api/v1/overview`: consolidated runtime, account, sync, rate-limit, candidate/reply, and recent-error view.
- `/api/stats`, `/api/attention`, `/api/outreach`: operator-level workload detail.
- `/api/events/stream`: realtime signal, not a replacement for snapshot checks.

Success should distinguish:

- process/container running;
- API reachable and authenticated;
- database/volume mounted;
- accounts restored and verified;
- bot intentionally paused or running;
- no crash loop or new high-severity errors;
- requested workload actually completed.

The authentication lease deliberately expires while an account is idle. A
start request revalidates the persisted Reddit and Matrix credentials before
changing the run state, so an otherwise valid paused account does not become
stuck behind the start safety gate. A failed revalidation still returns a
conflict and requires a fresh extension session import.

## Account session operations

The supported workflow is:

1. Load `extensions/reddit-session-exporter` into the operator's local Chrome.
2. Sign in to Reddit locally and open Reddit Chat.
3. Export a combined Reddit cookie + Matrix session JSON.
4. Upload it through Settings > Access.
5. Wait for both Reddit and Matrix identities to verify and for the matching runtime to be replaced/started.
6. Delete the local export file.

The dump is a bearer credential bundle. Do not inspect or paste it into logs. An account with one valid half is still unavailable for work.

## Incident diagnosis

### No new outreach

Check, in order: persisted bot running state, the per-account delivery states on Overview, enabled/running account count, full authentication, reply backlog, account send timer/hourly cap, account-specific Matrix cooldown, global Reddit cooldown, candidate funnel counts/reasons, enabled subreddit count, recent intake/screening logs, and OpenRouter failures.

Do not infer “no candidates” from “fetched N posts.” Inspect already processed/contacted, age/gender, seller, expired, AI skip, ready, retry, and rejected counts.

### Conversations appear stale

Separate Matrix remote acceptance from cached/dashboard visibility. Inspect Matrix identity/whoami, sync cursor/status, last full/delta sync, new event IDs, username enrichment, HTTP conversation snapshot, SSE validation/reconnect, and client query invalidation. A stale dashboard can coexist with a successful remote send.

### Reddit 403/429/404

- 429: honor `retryAfterMs` through the shared coordinator and avoid additional account requests.
- repeated/broad 403: treat as a possible service-wide anti-abuse block; inspect successful requests and shared cooldown rather than declaring every subreddit private.
- listing 404: the code disables that configured subreddit persistently.

### Database problems

Stop writers if recovery needs file operations. Back up the entire data directory, inspect SQLite `integrity_check`/`foreign_key_check`, WAL state, disk capacity/permissions, migration version, and recent logs. Do not create an empty replacement database over the original.

## Backup and destructive recovery

For routine backups, prefer a volume-level snapshot or a consistent SQLite online backup plus browser/media directories. For a reset:

1. State whether scope is one account, selected content, the RedditBot volume, the Compose application, or the Dokploy instance.
2. Capture and validate a backup.
3. Stop relevant writers.
4. Resolve explicit volume/container/app identifiers with read-only inspection.
5. Perform only the authorized deletion.
6. Recreate/deploy, then verify health, schema, accounts, and persistence.
7. Report what was removed and whether/how it can be restored.

## Routine checks

- Review attention items, failed/retrying candidates, reply backlog age, account authentication, invitation/global cooldowns, model errors/cost, and disk/volume health.
- Review response/image rates only with mature sample counts and by source/strategy/account context.
- Back up before migrations, account resets, or Compose/volume changes.
- Rotate dashboard, agent, OpenRouter, Reddit, and Matrix credentials after suspected exposure.

The concise account activation instructions in [`../DOKPLOY_DEPLOY.md`](../DOKPLOY_DEPLOY.md) complement this operational guide.