Skip to content

Operating Atlas

This section explains how to configure and run an Atlas installation after the first local evaluation. It covers the supported Compose topologies and the build-time distribution choices that determine which plugins are included.

Who this section is for

Use this section if you are responsible for configuration, deployment, distribution composition, migrations, service health, logs, shutdown, or recovery. It explains:

  • which topology is appropriate for development or production-like use;
  • which settings and secrets must be prepared before startup;
  • how selected plugins become an immutable distribution; and
  • how to verify or diagnose the running services safely.

Start here

Read Supported topologies first. It compares the source-mounted development topology with the immutable production-like one and defines the boundary of what Atlas currently supports.

  1. Supported topologies: choose the development or production-like Compose topology.
  2. Production-like topology: complete the secrets, host/origin, database, composition, startup-order, and health preflight. Then run immutable images behind the same-origin gateway.
  3. Choose an authentication method: compare local, OIDC, Gitea, custom providers, and unsupported browser/API capabilities.
  4. Follow the provider guide for local, OIDC, or Gitea, then configure Principal/Actor provisioning and Group reconciliation.
  5. Secure browser authentication: configure origins, outbound trust, sessions, recovery, secrets, and diagnostics.
  6. Migrate and revoke authentication state: move existing deployments and operate exact links and grants.
  7. Read-only accounts: restrict an account's writes, audit the change, recover from operator lockout, and plan safe rollout or rollback.
  8. Environment variables: review configuration ownership, required values, and secret handling.
  9. Assembling a distribution: select and validate the Core and plugin artifacts included at build time.
  10. Fix composition errors and change plugin lifecycle: correct validation failures and make selection changes safely.
  11. Database changes and data safety and upgrade: apply migrations, establish the backup boundary, and deploy an upgrade.
  12. Operations: run migrations, inspect logs, stop services, and intentionally reset local data.
  13. Troubleshooting: diagnose failures from an observable symptom.

Section boundary

Atlas documents Compose-based development and production-like topologies. It does not support Kubernetes or provider integrations that have not been implemented. Browser authentication does not add API bearer-token support. Use Getting Started for a first local run and Reference for exact configuration and contract lookup.