Deployment

Octopus ships as a single self-contained binary (octopus) and a multi-arch container image. There is no separate control plane to run: the gateway, its health probes, its Prometheus /metrics endpoint, and — when enabled — the in-process Kubernetes operator all live in the same process, listening on one port.

Note

The gateway serves everything on its listen port (default 0.0.0.0:8080): proxied traffic, the /livez / /readyz / /startupz probes, and /metrics. There is no second listener to expose. See Ports for what the 9090 you may have seen in older examples actually refers to.

Deployment options01

Docker→

Run the published ghcr.io/xraph/octopus image, mount a config file, and substitute environment variables.

Kubernetes→

Helm chart and raw manifests, the in-process operator, and EndpointSlice discovery — covered in the Kubernetes section.

From source→

Build an optimized binary with make release and run it directly or under a process supervisor.

From source02

If you do not want the container image, build the binary yourself. Building requires Rust 1.75 or newer and protoc (the Protocol Buffers compiler, used by the gRPC code paths); on Linux you also need pkg-config and libssl-dev.

git clone https://github.com/xraph/octopus.git
cd octopus
make release

The optimized binary is written to target/release/octopus. Run it against a config file:

target/release/octopus serve --config /etc/octopus/config.yaml

octopus serve accepts multiple -c/--config flags or a directory; files are merged in order so base settings and environment overrides can live separately. Validate a config before rolling it out:

octopus validate -c /etc/octopus/config.yaml

When supervising the binary (systemd, a process manager, or any orchestrator), send SIGTERM to trigger graceful shutdown rather than killing it — see Graceful shutdown. For installation methods and platform notes, see Installation.