Skip to content
Menu

First deployment#

This page takes a released gateway image onto a pre-production host for the first time, using the trial kit in trial/. You start one gateway and one throwaway app, sign in, check health and logs, roll back, and tear it down. No real app is behind the gateway. The trial kit is the drill before the drawbridge goes over a real moat.

What the trial kit is#

trial/ holds the smallest real deployment, ready to copy onto a host:

File What it is
compose.yaml Two services: gateway (the image under trial) and whoami (a one-file app, run on the same image).
drawbridge.example.yaml The gateway config: one app with a path of every kind, so drawbridge smoke checks every rule.
.env.example The image tag, the port, the platform settings and the empty secrets.
whoami/index.php The throwaway app. It answers one JSON page: who the gateway says you are, and whether that holds up.
.gitignore Keeps .env, drawbridge.yaml and keys/ out of git.

The whoami app checks the signed assertion the way an app's SESAME gateway driver would (the ES256 signature against the key set file, typ, audience, expiry) with nothing but PHP's openssl, so the host pulls one image and nothing else. It has no published port: the only way to it is through the gateway. It is a test instrument, not an example to copy; a real app verifies with SESAME.

rig/run.sh trial (rig\run.ps1 trial on Windows) runs this same compose file with the rig's mock provider in place of Entra, signs in through whoami, runs the smoke check, then rolls back and checks again. If that is green on your machine, the kit works; what is left to prove is the host.

Before you start#

  • Docker with the compose plugin on the host, and a way to pull the release from the stack's image registry (Getting the image).
  • A host name for the trial app, sent by the front proxy (or a load balancer) to this host's port.
  • An Entra app registration for the trial, with the redirect URI https://<the trial host>/_drawbridge/oidc/callback (Register Drawbridge in Entra ID). Use a trial registration, not a real app's.
  • Outbound HTTPS from the host to login.microsoftonline.com: the gateway fetches the provider's metadata and keys.

Step 1: Copy the kit and fill in the files#

Copy trial/ to the host and work inside it.

cp .env.example .env
cp drawbridge.example.yaml drawbridge.yaml

In .env, set DRAWBRIDGE_IMAGE to the release (a tag, or better its digest), the client secret and the date it expires (YYYY-MM-DD, as Entra shows it), a crypto passphrase of at least 32 characters, and a metrics token. In drawbridge.yaml, set the three values marked CHANGE: the gateway's issuer, the tenant issuer and client id, and the app's host. Then check the config with the image itself:

IMAGE=<the same value as DRAWBRIDGE_IMAGE>
docker run --rm --entrypoint php -v "$PWD/drawbridge.yaml:/etc/drawbridge/drawbridge.yaml:ro" "$IMAGE" \
  /opt/drawbridge/bin/drawbridge config:validate --config=/etc/drawbridge/drawbridge.yaml

Step 2: Make the signing key and the key set file#

The gateway signs every assertion with a private key; whoami (and any real app) verifies with the public key set file. The kit keeps the two apart: keys/private goes to the gateway only, keys/public to whoami only.

mkdir -p keys/private keys/public
docker run --rm --user "$(id -u):$(id -g)" --entrypoint php -v "$PWD/keys:/keys" "$IMAGE" \
  /opt/drawbridge/bin/drawbridge keys:generate --private=/keys/private/signing.key --public=/keys/public/signing.pub
docker run --rm --user "$(id -u):$(id -g)" --entrypoint php -v "$PWD/keys:/keys" "$IMAGE" \
  /opt/drawbridge/bin/drawbridge keys:jwks --key=trial-1=/keys/public/signing.pub --out=/keys/public/jwks.json
sudo chown -R 1001:0 keys/private

keys:generate writes the private key readable by its owner only, and the gateway runs as user 1001, so the last line hands the folder to that user. The kid (trial-1) must match DRAWBRIDGE_SIGNING_KEY_ID in .env. The key is for this trial only: never reuse it for a real deployment.

Step 3: Start it#

The compose shape, from the kit's folder:

docker compose up -d
docker compose ps

The gateway publishes 127.0.0.1:8080 by default (DRAWBRIDGE_TRIAL_BIND and DRAWBRIDGE_TRIAL_PORT move it), so only the front proxy on the same host, or an SSH tunnel, reaches it. Both containers drop every Linux capability, cannot gain privileges, restart unless stopped, and rotate their logs at 10 MB.

The same gateway without compose, for a platform that runs plain containers. The upstream in drawbridge.yaml is http://whoami:8080, so both containers share a network:

docker network create drawbridge-trial
docker run -d --name whoami --network drawbridge-trial --restart unless-stopped \
  --cap-drop ALL --security-opt no-new-privileges:true --no-healthcheck \
  -e WHOAMI_JWKS_FILE=/keys/jwks.json -v "$PWD/whoami:/whoami:ro" -v "$PWD/keys/public:/keys:ro" \
  --entrypoint php "$IMAGE" -S 0.0.0.0:8080 /whoami/index.php
docker run -d --name drawbridge-gateway --network drawbridge-trial --restart unless-stopped \
  --cap-drop ALL --security-opt no-new-privileges:true \
  --env-file .env -e DRAWBRIDGE_CONFIG=/etc/drawbridge/drawbridge.yaml \
  -e DRAWBRIDGE_SIGNING_KEY_FILE=/run/drawbridge/signing.key \
  -v "$PWD/drawbridge.yaml:/etc/drawbridge/drawbridge.yaml:ro" -v "$PWD/keys/private:/run/drawbridge:ro" \
  -p 127.0.0.1:8080:8080 "$IMAGE"

The rest of this page uses the compose commands; with plain containers, use docker exec drawbridge-gateway and docker logs drawbridge-gateway in their place.

Step 4: Health and the smoke check#

The image's health check asks the gateway for /_drawbridge/up on its default host every 15 seconds. docker compose ps shows healthy once Apache answers. To ask yourself:

curl -fsS http://127.0.0.1:8080/_drawbridge/up

Then run the smoke check inside the gateway container. It needs no sign-in, no browser and no options: it reads the config, the public scheme and port, and the metrics token from the container.

docker compose exec gateway /opt/drawbridge/bin/drawbridge smoke

It checks that the gateway is up and refuses an unknown host, and, for the whoami app, that a protected path sends a visitor to sign in with the right redirect URI (and, on https, a state cookie marked Secure), an api path answers 401, a deny path answers 403, a public path reaches whoami without a spoofed identity header getting through, the security headers are set, whoami's clock is within 10 seconds of the gateway's, a forged callback gets no session, and /metrics refuses a stranger and serves the token. It ends with the version the gateway reports. Exit code 0 means every check passed. Commands lists the checks and exit codes.

Two first-run failures, both seen while this page was tested:

What you see Why Fix
The gateway restarts over and over, and its log says cannot read /run/drawbridge/signing.key The key is readable by its owner only, and that is not user 1001. The chown line in step 2.
Smoke's login line fails with answers 500 ... could not get the provider's metadata The gateway fetches the provider's metadata on the first sign-in, not at start, so a wrong oidc.issuer or no outbound HTTPS shows up here. Read the auth_openidc:error lines in docker compose logs gateway; they name the cause (an unknown tenant, a refused connection).

Step 5: Sign in#

Open https://<the trial host>/ in a browser, sign in with Entra, and read the page. A good sign-in shows "signed_in": true, your user name, and every entry under checks true. https://<the trial host>/up is the public path: it shows no assertion at all.

In the browser's developer tools, look at the cookies for the trial host. With DRAWBRIDGE_COOKIE_SECURE=true the session cookie is __Host-drawbridge and carries Secure, HttpOnly and SameSite=Lax. A browser drops a __Host- cookie that lacks Secure, so if the gateway misread the scheme behind the front proxy you would not stay signed in at all: it fails closed. This is the one cookie check the rig cannot make, because the rig is plain http. Note what you saw (it closes an open question).

Step 6: Logs and metrics#

docker compose logs gateway --since 10m
docker compose logs gateway | grep '^{"v":1,'

The gateway writes the access log (no query strings) and the event log to standard output. Event lines start with {"v":1, and cover sign-ins, failed sign-ins, sign-outs, refusals and revoked sessions (Log events). They never hold a token, a cookie or a secret. Set DRAWBRIDGE_EVENT_LOG to a file on a mounted volume to keep them apart for a log shipper.

/metrics answers on the app's host to the metrics token:

curl -fsS -H "Host: <the trial host>" -H "Authorization: Bearer <the metrics token>" http://127.0.0.1:8080/metrics

drawbridge_build_info names the running release, and drawbridge_oidc_client_secret_days_left counts down to the expiry date in .env (Metrics).

Step 7: Roll back#

Rolling back moves the gateway to the previous release and leaves whoami running. Put the previous release in DRAWBRIDGE_IMAGE in .env, then:

docker compose up -d --no-deps gateway
docker compose exec gateway /opt/drawbridge/bin/drawbridge smoke

--no-deps recreates the gateway only. The smoke check's last line names the release now running. Sessions live in the gateway's memory by default, so everyone signs in again after a rollback (or any restart); with the Redis session store they carry over (Sessions and lifetimes). The signing key and the key set file do not change, so nothing downstream needs to know. To roll forward, put the new release back and run the same two lines.

Step 8: Tear it down#

docker compose down

Then remove the kit's folder, which holds the trial key and the secrets. Delete the trial's client secret in Entra when the trial is over.

What to send back#

  • The release you ran (the smoke check's last line) and its digest.
  • The smoke check's output, from the first start and after the rollback.
  • Whether the browser sign-in showed every check true, and the session cookie's name and flags.
  • Any event lines with a reason, and anything in the logs you did not expect.