Skip to main content

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. People who change the code need the Contributor guide.

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, 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 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 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 lists every outbound destination and when it is used, also the ones that the diagram leaves out. The threat model 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 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 covers the operator console. Integrations covers workspace connections.

Set it up in this order​

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

Keep it running​

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

Repository scans​

Scan a repository 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.