# Configuring and operating Flexway

> Each page says what of it is built and since which version. The versions named are roadmap milestones, not release tags: a release ships every milestone…

Concept - Since version 0.1.0 - Flexway v1.6.3 - https://flexway.io/en/docs/operations-overview/

> Operations guide: configure, deploy and observe the gateway. What the capability does, product side: [product guide](https://flexway.io/en/docs/product-overview/); calling it: [developer guide](https://flexway.io/en/docs/developer-overview/).

> Each page says what of it is built and since which version. The versions named are **roadmap
> milestones**, not release tags: a release ships every milestone merged before it, and what a tag
> contains is in the [releases](https://github.com/flexwiz/flexway/releases).

## 1. Prerequisites

> - A valid **OpenAPI 3.1** contract. It is the only mandatory input.
> - A container engine, **or** just the binary - with [`cosign`](https://docs.sigstore.dev/cosign/system_config/installation/)
>   to verify what you download.
> - For identity: your OIDC provider's discovery URL.
> - For rates shared across replicas and tenant quotas: a Redis, Dragonfly or Valkey.
>   **Optional** - without one, counters are local to each replica and no tenant quota can be
>   declared.

Nothing else. No database, no control plane, no prior sign-up.

**The binary** (a VM, bare metal): each release carries `flexway_<version>_linux_<arch>.tar.gz`
(`amd64`, `arm64`) - the very bytes of its image, copied out of it - and `SHA256SUMS`, signed.

```bash
v=$(gh release view -R flexwiz/flexway --json tagName -q .tagName | sed 's/^v//'); arch=amd64   # the latest
gh release download "v$v" -R flexwiz/flexway -p "flexway_${v}_linux_${arch}.tar.gz" -p 'SHA256SUMS*'
cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  --certificate-identity-regexp '^https://github.com/flexwiz/flexway/.github/workflows/release.yml@' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf "flexway_${v}_linux_${arch}.tar.gz" && sudo install "flexway_${v}_linux_${arch}/flexway" /usr/local/bin/
```

Once a `flexway.yaml` exists ([Serving your first API](https://flexway.io/en/docs/operations-first-api/)), the binary is the service - under systemd or any supervisor,
configured by its environment only:

| Variable | Default | Role |
| --- | --- | --- |
| `FLEXWAY_CONFIG` | - (**required**) | The `flexway.yaml` to serve; the process refuses to start without it |
| `FLEXWAY_ADDR` | `:8080` | Traffic listener |
| `FLEXWAY_ADMIN_ADDR` | `:9090` | Admin listener: `/healthz`, `/readyz`, `/metrics`, `/config` - never routable from outside |
| `FLEXWAY_TLS_ADDR` | `:8443` | The gateway's own TLS listener, when `server.tls` is set |

```bash
FLEXWAY_CONFIG=/etc/flexway/flexway.yaml flexway     # SIGTERM drains, SIGHUP reloads
```

## 2. The sequence

```mermaid
%%{init: {'theme':'base','themeVariables':{'fontSize':'13px','lineColor':'#94a3b8'}}}%%
sequenceDiagram
  participant U as You
  participant C as flexway (CLI)
  participant G as flexway (service)
  participant A as Upstream

  U->>C: flexway validate
  Note over C: offline - contract + configuration
  C-->>U: every operation has an upstream, or it fails
  U->>G: start
  Note over G: same checks, refuses to start if partial
  U->>G: call a declared operation
  G->>A: relay
  A-->>G: response
  G-->>U: response + trace + metrics
```

> This sequence **runs** since `0.2.0`: `flexway validate` offline, a refusal to start on a partial
> configuration, unbuffered relaying, traces and metrics, and identity since `0.3.0`. The API
> plane's audit line is the chained decision log, delivered in `1.0.0` (
> `audit.decisions`); without it, refusals are logged with a hashed subject.