Deployment

Recommended topology: one VPS and SQLite

Run one Argus instance on a supported Linux VPS. This is the supported onboarding path and the smallest complete deployment: one Argus service runs the API, scheduler, worker, and optional processor with runtime.role: all and SQLite.

Use one of Ubuntu 22.04, Ubuntu 24.04, Ubuntu 25.10, Ubuntu 26.04, Debian 12, or Debian 13 on Linux amd64/x64 or arm64/aarch64. The host needs a sudo-capable account, outbound HTTPS, Docker Engine with the Compose plugin and daemon access, at least 5 GiB free disk, and 1 GiB memory. Choose 2 GiB when onboarding managed SearXNG. Onboarding also verifies that the selected API port is free before it writes an instance.

Inspect the installer before making host changes, then install and onboard:

curl -fsSLo /tmp/argus-install.sh https://argus.gpsxtre.me/install.sh
ARGUS_INSTALL_INSPECT=1 sh /tmp/argus-install.sh
# After review, run the exact file inspected above.
sh /tmp/argus-install.sh
argus onboard
argus status --json
argus doctor --json

The instance root is /opt/argus. The CLI owns its generated Compose file and state; do not edit them to change a deployment.

What the generated Compose deployment contains

Every managed Compose deployment has these networks:

• argus-private is internal. Argus, PostgreSQL when selected, managed SearXNG, and VPS-hosted FxEmbed use it.
• argus-egress lets source-facing services reach the public Internet. Argus, managed SearXNG, and VPS-hosted FxEmbed use it.

The argus service mounts /opt/argus/argus.yaml read-only and the persistent argus-data volume at /app/data. It reads /opt/argus/secrets.env as its environment file. Docker publishes the selected API port, default 8788, from the host to the container. Put a firewall or reverse proxy in front of a publicly reachable host port; setting a loopback API host is not the same thing as removing Docker's published port.

SQLite is stored through argus-data; there is no separate database container. Selecting PostgreSQL adds a postgres service and the persistent postgres-data volume. Selecting managed SearXNG adds a searxng service with the CLI-owned /opt/argus/searxng/settings.yml. Selecting VPS FxEmbed adds the signed, digest-pinned fxembed service. Neither service publishes a host port.

state.json records the verified deployment and pinned image references. release-context.json keeps the signed release material used to identify a rollback release. backups/ and update-state.json are update recovery state. They are operational state, not application configuration; preserve them and do not hand-edit them.

Managed and external dependencies

Managed SearXNG is available only for Web query targets. Argus checks it with a bounded JSON search and can recreate only this managed service with argus repair searxng. An external SearXNG endpoint is outside Argus's control: Argus can check it, but it will not repair or change it.

VPS-hosted FxEmbed is the default for X. Argus runs the pinned Worker bundle through its local Workers runtime at http://fxembed:8787, reachable only inside Compose. It participates in lifecycle, status, logs, doctor, targeted repair, signed update, and rollback. Cloudflare-hosted and external FxEmbed remain advanced alternatives; Argus cannot repair an external endpoint or Cloudflare account configuration.

Advanced PostgreSQL roles

Use PostgreSQL when the runtime needs independent api, scheduler, worker, or processor processes. SQLite is invalid for every role except all; it is not a multi-process or multi-role storage mode.

All role processes use the same validated configuration and PostgreSQL database. ARGUS_ROLE overrides runtime.role for a process. Run at least an API role for the HTTP API, a scheduler role to enqueue due work, and a worker role to collect it; add a processor role only for scheduled intelligence processors. PostgreSQL job leases expire, so a crashed worker's work can be retried without Redis or Kafka.

The generated VPS Compose topology still starts a single all Argus service. Splitting roles is an advanced operator-managed deployment concern; the CLI does not render a multi-replica Compose layout.

Railway boundary

The repository includes Railway templates in deploy/railway/ for api, scheduler, worker, and processor roles. Use PostgreSQL and set ARGUS_ROLE for each service. These templates are not a Railway control plane: argus onboard, lifecycle commands, managed Compose repair, update backup, and rollback operate on the /opt/argus Docker VPS instance, not on Railway services. Use Railway's own deployment, secret, database backup, and recovery controls for that topology.

Backup boundary

The managed SQLite database is in Docker's named argus-data volume, which Compose creates as argus_argus-data because the project name is argus. Confirm that identity without changing the instance before every backup or update:

cd /opt/argus
docker compose -p argus config --volumes
docker volume inspect argus_argus-data

For SQLite, a signed update proves that exact Compose-owned volume, stops the Argus writer, and creates a consistent snapshot beneath /opt/argus/backups. The updater records its hash, size, integrity result, table counts, and volume identity before pulling or migrating. argus update --rollback revalidates the snapshot and atomically restores it inside argus_argus-data before starting the prior signed release. Keep a separately verified operator-managed Docker-volume backup for disaster recovery; the update snapshot is not a substitute for an independent backup policy.

For PostgreSQL, take regular pg_dump/pg_restore backups or provider snapshots and store them outside /opt/argus. Argus deployment backups do not contain a PostgreSQL dump. After a database restore, start the required runtime roles and verify with argus status --json and argus doctor --json on a managed VPS.

Next step

Read operations for inspect/apply/verify sequences and security before exposing the API or granting optional Cloudflare credentials.