Installation

Octopus ships as a single binary, octopus, and as a multi-arch container image. The same binary serves traffic, validates configuration, generates clients, and — when kubernetes.enabled is set — runs the in-process operator.

Prerequisites01

Installation methods02

docker pull ghcr.io/xraph/octopus:latest

helm install octopus oci://ghcr.io/xraph/charts/octopus \
  --namespace octopus --create-namespace

Verify the installation03

# Print version information
octopus version

# View help
octopus --help

Create a configuration file04

The only required section is gateway with a listen address. A minimal static config — one upstream and one route:

gateway:
  listen: "0.0.0.0:8080"
  workers: 0                 # 0 = one worker per CPU core

upstreams:
  - name: example-service
    lb_policy: round_robin
    instances:
      - id: example-1
        host: 127.0.0.1
        port: 8081

routes:
  - path: /api
    methods: [GET, POST]
    upstream: example-service
    strip_prefix: /api

Validate it without starting the server, then run it:

octopus validate -c config.yaml
octopus serve -c config.yaml

Health and metrics endpoints05

Once running, the gateway serves Kubernetes-style health probes on the listen port and Prometheus metrics on the metrics endpoint:

curl http://localhost:8080/livez      # liveness — 200 while the process is alive
curl http://localhost:8080/readyz     # readiness — 200 when ready to serve traffic
curl http://localhost:8080/startupz   # startup — 200 once the listener has bound
curl http://localhost:9090/metrics    # Prometheus metrics

See Health probes and Metrics for details.

Upgrading06

Docker

docker pull ghcr.io/xraph/octopus:latest
docker restart octopus

From source

cd octopus
git pull
make release
sudo install -m 0755 target/release/octopus /usr/local/bin/octopus

Helm

helm upgrade octopus oci://ghcr.io/xraph/charts/octopus -n octopus

Next steps07

Troubleshooting08

Command not found

If octopus is not found after installing from source, make sure the install directory is on your PATH (or run the binary by its full path, e.g. ./target/release/octopus):

echo "$PATH"

Port already in use

If the gateway fails to bind with "address already in use", find the process holding the port or change gateway.listen in config.yaml:

lsof -i :8080

gateway:
  listen: "0.0.0.0:8081"   # bind a different port

For runtime debugging via logs and metrics, see Observability. For task-focused walkthroughs, see the Guides. You can also open an issue.