Deployment

One-command TLS demo

An end-to-end demo stack with Dwara doing TLS termination (the gateway decrypts TLS itself) in front of an nginx demo upstream, in quickstart/oss/ at the repository root:

cd quickstart/oss
../gen-certs.sh          # self-signed localhost certificate into ../certs
docker compose up        # builds the gateway image
curl --cacert ../certs/server.crt https://localhost:8443/

Linux hosts need sudo chown -R 65532:65532 quickstart/certs before docker compose up (the distroless image runs as UID 65532).

The OSS quickstart demo page is the canonical walkthrough -- everything the demo covers, the admin API, and teardown. The sibling quickstart/enterprise/ directory runs the Enterprise edition's CP/DP split topology instead (controller + edge fleet); see the Enterprise quickstart demo.

Docker

See Installation for the image variants and their tradeoffs. In short: use Dockerfile.scratch when your orchestrator can inject a non-root user, Dockerfile.distroless otherwise.

systemd

See Installation.

TLS termination and passthrough

A listener can terminate TLS (including multi-SNI (Server Name Indication — lets one port serve multiple TLS certificates by the requested hostname), one certificate per server_name) or pass a TLS connection straight through to the upstream based on the ClientHello's (the first TLS handshake message, which carries the SNI) SNI, without decrypting it. Passthrough (the gateway forwards the encrypted connection without decrypting it) is useful when the upstream itself must see the original TLS session (its own certificate, mTLS to the client, etc.) — Dwara only reads the SNI from the ClientHello to pick an upstream, then splices bytes.

listeners:
  - name: https
    address: 0.0.0.0
    port: 8443
    tls:
      mode: terminate
      certificates:
        - server_name: api.example.com
          cert_file: /etc/dwara/certs/api.crt.pem
          key_file: /etc/dwara/certs/api.key.pem

Certificate files are watched and hot-reloaded without dropping connections — see Operations.

Release artifacts

Tagged releases (v*) are the only builds that produce distributable artifacts — nothing builds on pushes to main or on pull requests. A tag cross-builds amd64/arm64 musl binaries under a 25 MB stripped-size bar (enforced via LTO (link-time optimization)), and publishes multi-arch GHCR (GitHub Container Registry) images assembled from those verified binaries (checksums re-verified before the COPY, so the image matches the released tarball byte-for-byte).

Generating the config schema reference

The machine-readable JSON Schema (a standard for describing a JSON document's shape) of the gateway config lives at config-reference.json in the repository root, and is regenerated by:

dwara-cli schema > config-reference.json

If you maintain your own tooling against Dwara's config shape (editors, linters, generators), this is the schema to consume — CI fails a pull request whose committed schema drifts from what the current code generates, so it never goes stale.

Runnable demo

Run TLS transport against a live gateway: demos/10-tls-transport/ in the repository. test-01-tls-terminate.sh and test-02-multi-sni.sh exercise TLS termination and multi-SNI certificate selection; SNI passthrough is configuration-only -- the demo's plaintext upstreams cannot complete a passthrough handshake, so that live test is skipped. The category README covers prerequisites and teardown.