# Admin overview

This guide is for people who run a Hephaestus deployment. It has five parts:

* **Deploy** installs the supported stack.
* **Configure** connects providers, AI models, and practices.
* **Operate** covers upgrades, backups, troubleshooting, and incidents.
* **Security and compliance** covers the threat model, keys, release verification, legal pages, and data protection.
* **Reference** lists every setting, the runtime roles, network egress, sizing, and what a version number promises.

Developers who use Hephaestus need the [User guide](/user/overview.md). People who change the code need the [Contributor guide](/contributor/overview.md).

## What a deployment consists of

One application image starts in three runtime roles: `server`, `worker`, and `webhook`. A deployment also has PostgreSQL and a NATS event buffer. On [Kubernetes](/admin/kubernetes.md#what-the-chart-runs), the Helm chart runs them on a cluster or on one host with k3s, and a Gateway API controller handles TLS. The deprecated [Docker Compose stack](/admin/install.md) runs them on one host with Traefik for TLS.

Sign-in uses a GitHub or GitLab OAuth app that you register during installation. The worker starts a sandboxed container for each practice review. It does not keep that container active between reviews. [Runtime roles](/admin/runtime-roles.md) explains each role and why the webhook role has its own container.

## Architecture and network

The diagram shows the deprecated Compose stack on one host. On Kubernetes, the roles run as Pods, a Gateway replaces Traefik, and the worker starts sandboxes through the Kubernetes API. Each box is a container, and each arrow is one of its main connections. [Network egress](/admin/network-egress.md) lists every outbound destination and when it is used, also the ones that the diagram leaves out. The [threat model](/admin/threat-model.md#system-and-data-flow) shows the trust boundaries of the same system.

<!-- -->

Only `application-worker` starts containers through the Docker socket. `reverse-proxy` mounts the socket read-only to discover its routes.

Only `reverse-proxy` publishes ports, 80 and 443. Browsers, OAuth callbacks, and provider webhooks arrive there. Each Java container has a management port, 9090, for health and metrics. That port, PostgreSQL, and NATS stay on the internal Compose network. [Runtime roles](/admin/runtime-roles.md) explains what each role does.

## Two kinds of admin

* **Instance admin** — operates the whole deployment. This includes AI providers, instance-wide settings, and the practice catalog that workspaces can adopt from.
* **Workspace admin** — configures one workspace. This includes its repositories, practices, members, AI model, and cap on AI spend.

A person can be both. [Instance admin](/admin/instance-admin.md) covers the operator console. [Integrations](/admin/integrations.md) covers workspace connections.

## Set it up in this order

1. [Install the Helm chart](/admin/kubernetes.md), on a cluster or on one host with k3s. Then follow [First steps](/admin/first-steps.md) for the login provider, the first admin, and the first review. The [Docker Compose install](/admin/install.md) is deprecated and stays supported until 1.0.0, as [Supported deployment](/admin/compatibility-policy.md#supported-deployment) states.
2. [Connect a source](/admin/integrations.md): a GitHub App or GitLab connection that supplies repository activity. [Integration settings](/admin/production-setup.md) covers Slack and Outline.
3. [Connect an AI provider](/admin/ai-providers.md) with a supported API.
4. Set a cap on AI spend.
5. [Choose practices](/admin/practice-catalog.md) for the instance to include and the workspace to adopt. [Practice review](/admin/practice-review.md) explains how a review runs.
6. [Publish the legal pages](/admin/legal-pages.md) with imprint and privacy information for your deployment. The [data-protection documentation](/admin/dsms.md) has the GDPR records.

## Keep it running

* [Upgrade](/admin/upgrade.md) owns the upgrade procedure, failed-migration recovery, and rollback. Before an upgrade, read the [compatibility policy](/admin/compatibility-policy.md) and the [migration guide](https://github.com/hephaestus-build/Hephaestus/blob/main/MIGRATION.md).
* [Backup & restore](/admin/backup-restore.md) covers recovery.
* [Troubleshooting](/admin/troubleshooting.md) lists common failures and their fixes.
* [Sizing and scaling](/admin/sizing.md) gives the resource budget.
* The [production operations runbook](/admin/production-operations-runbook.md) covers incident brakes, silent deployment, PostgreSQL × JetStream restore, and removal of external feedback.
* [Practice review operations](/admin/practice-review-operations.md) and [webhook ingestion operations](/admin/webhook-ingestion-operations.md) cover the two pipelines whose failures are most visible.

Hephaestus is pre-1.0. A minor release can still require action.

## Repository scans

[Scan a repository](/admin/practice-scans.md) explains default-branch review and SARIF export. Scan reports separate judged, reused, withheld and unreviewed work. They do not produce personal feedback or developer standing.