Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.

On this page

Install the server

This page installs the Bouncer server and PostgreSQL with Docker Compose, and connects them to your OpenBao. It takes about an hour the first time, most of it reading.

Before you start: read Overview and prerequisites and complete its preparation checklist. OpenBao must already be running and unsealed, with a KV version 2 mount. Do not initialise an existing OpenBao again. If you don't run OpenBao yet, set it up first with OpenBao for Bouncer.

The examples use bouncer.example.com for the Bouncer server's address and openbao.example.com for OpenBao. Use your own.

Step 1: get the files onto the server

There are two ways, and the rest of the page is the same for both except step 4:

  • From a release download: you load a ready-made image, so the server needs no access to the source and never compiles anything. 0.5.5 was the first release with the server files; check them with the release's combined SHA256SUMS and --ignore-missing. The 0.5.6 build introduced its own bouncer-server-<version>-SHA256SUMS, which lists only the server files. The private 0.5.7 release uses the same layout. Get Bouncer says what they are.
  • From the source: you clone the repository and build the image on the server in step 4. This needs access to the source repository, and 4 GB or more of memory while it builds.

Do either one as a normal user who can run docker.

.env, which both ways make, holds settings, never secrets: the port, the folders and the image name. The defaults are a good start: port 8080, the config in /etc/bouncer/config, the secret files in /etc/bouncer/secrets.

1a. From a release download

The release's INSTALL-SERVER.md has these steps with that release's exact names, commit and image ID. Follow it, except for its checksum step: in 0.5.5 the guide runs sha256sum -c SHA256SUMS, which also lists the app and CLI files and reports the ones you didn't download as missing. Use step 1 below instead. Put the image, kit, guide and checksum file in one folder, then:

  1. Check the files against the release's combined SHA256SUMS. For 0.5.5:

    sha256sum -c SHA256SUMS --ignore-missing
    

    It must say OK for each file you downloaded. If one says FAILED, download it again and don't use it. --ignore-missing skips app and CLI files you didn't download. For a release that includes bouncer-server-<version>-SHA256SUMS, use sha256sum -c bouncer-server-<version>-SHA256SUMS instead; it lists only the three server files.

  2. Load the image:

    gunzip -c bouncer-server-<version>-image.tar.gz | docker load
    

    It ends with Loaded image: localhost/bouncer-server:<short commit>. With Podman: podman load -i bouncer-server-<version>-image.tar.gz.

  3. Check the image is the release's. Read its revision and version labels:

    docker image inspect localhost/bouncer-server:<short commit> \
      --format '{{index .Config.Labels "org.opencontainers.image.revision"}} {{index .Config.Labels "org.opencontainers.image.version"}}'
    

    It must print the release's full commit and version, exactly as INSTALL-SERVER.md shows them. If it doesn't, stop.

  4. Unpack the kit into a folder of its own, so the release before it stays for a rollback, and point .env at the image you loaded:

    mkdir -p ~/bouncer-releases
    tar -xzf bouncer-server-<version>-compose.tar.gz -C ~/bouncer-releases
    cd ~/bouncer-releases/bouncer-server-<version>/deploy/compose
    cp .env.example .env
    sed -i 's|^BOUNCER_IMAGE=.*|BOUNCER_IMAGE=localhost/bouncer-server:<short commit>|' .env
    printf 'BOUNCER_VERSION=%s\nBOUNCER_REVISION=%s\n' '<version>' '<full commit>' >> .env
    

    The last two lines record the release in .env and in the image's labels.

From here on, wherever these pages say ~/bouncer, your folder is ~/bouncer-releases/bouncer-server-<version>. The role kit is in it, at deploy/openbao-role-kit.

1b. From the source

Clone the repository. Ask whoever gave you access to Bouncer for the repository link. Check out a release tag, or a commit you have chosen:

git clone <repository URL> ~/bouncer
cd ~/bouncer
git checkout <tag or commit>
cd deploy/compose
cp .env.example .env

A strict umask

If your umask is stricter than the usual 022 (umask prints 0077 or 0027), PostgreSQL's user inside its container can't read the kit's folder and stops at its first start. This applies to both ways. Make the folder readable; nothing in it is secret:

chmod -R a+rX ~/bouncer/deploy/compose

Our test run hit this: PostgreSQL exits with code 2 and its log repeats ls: cannot open directory '/docker-entrypoint-initdb.d/': Permission denied.

Step 2: set up Bouncer's role on OpenBao

Bouncer logs in to OpenBao with AppRole, OpenBao's login method for programs. A program logs in with two values: a role_id, which names the role, and a secret_id, which works like a password. The role kit (deploy/openbao-role-kit) creates that role, with policies that only let Bouncer issue short tokens for the secrets you list, and revoke them.

Run the kit on any machine that has an OpenBao admin token, a token allowed to manage policies, token roles and login methods. It doesn't have to be the Bouncer server. On a new dedicated OpenBao, that's the root token on your recovery workstation (OpenBao for Bouncer, step 5).

2a. Choose kit settings

List your secrets in the kit's resources file:

cd ~/bouncer/deploy/openbao-role-kit
cp resources.example resources
$EDITOR resources

Each line of resources is one secret:

# <resource-id>     <kv-mount>  <kv-path>                    [max-ttl-seconds]
prod-db-password    kv          apps/billing/db-password     120
deploy-token        kv          services/deploy/token

The resource ID is Bouncer's name for the resource. The KV mount must be a KV version 2 mount, and the path is the secret's path inside it, without data/. You will list the same resources in Bouncer's config file in step 3. While you test, use a secret that doesn't matter, such as the bouncer-test secret from OpenBao for Bouncer, step 4.

Then decide two settings in the kit's kit.env, before setup.sh runs for the first time. Changing them later makes the kit treat the change as a possible hand edit and ask for extra flags. Without a kit.env, the defaults apply.

cp kit.env.example kit.env
$EDITOR kit.env
  • SECRET_ID_TTL: how long Bouncer's secret_id lasts, 90 days by default. OpenBao also caps it at the AppRole mount's maximum lease time, often 32 days; step 2d shows the real lifetime.
  • SECRET_ID_BOUND_CIDRS: the addresses Bouncer may log in from, for example 10.0.0.10/32. Off by default.

2b. Apply the kit

export BAO_ADDR=https://openbao.example.com:8443
bao login                   # your admin token, unless BAO_TOKEN is already set
./setup.sh --dry-run        # read what it would do
./setup.sh                  # apply it; type yes
./setup.sh --verify         # must say everything matches

Expected result: setup.sh ends by telling you to run the check, and --verify exits 0.

2c. Run the check

The check logs in as Bouncer with a single-use login and lists what the role can and can't do:

(umask 077
 bao read -field=role_id auth/bouncer-approle/role/bouncer-server/role-id > check.role_id
 bao write -f -field=secret_id auth/bouncer-approle/role/bouncer-server/secret-id ttl=10m num_uses=1 > check.secret_id)
BOUNCER_ROLE_ID=$(cat check.role_id) BOUNCER_SECRET_ID=$(cat check.secret_id) ./check.sh
rm -f check.role_id check.secret_id

Expected result: it ends with Summary: N checks, N ok. and exits 0. Against a fresh OpenBao 2.7.2, our test runs reported Summary: 47 checks, 47 ok. with the example resources, and Summary: 34 checks, 34 ok. with only the bouncer-test resource. The number depends on your resources. Don't carry on until it passes.

2d. Make Bouncer's own credentials

First check how long OpenBao will let the secret_id last. OpenBao caps it at the AppRole mount's maximum lease time, whatever SECRET_ID_TTL says:

bao read -field=max_lease_ttl sys/auth/bouncer-approle/tune

It prints seconds. 2764800 (32 days) is OpenBao's usual default. For the full 90 days the answer must be at least 7776000. To raise it, use a full admin token (a scoped bouncer-kit-admin token, described in OpenBao for Bouncer, step 5, can't change it):

bao auth tune -max-lease-ttl=2160h bouncer-approle

Then make the two values straight into files, in a new private folder outside the repository, so they never appear on screen or in your shell history. The commands also print how long the secret_id really lasts. Copy the files to the Bouncer server and destroy the copies here:

HANDOVER=$(mktemp -d)
(umask 077
 bao read -field=role_id auth/bouncer-approle/role/bouncer-server/role-id > "$HANDOVER/bouncer-role-id"
 bao write -f -format=json auth/bouncer-approle/role/bouncer-server/secret-id > "$HANDOVER/secret-id.json"
 jq -j .data.secret_id "$HANDOVER/secret-id.json" > "$HANDOVER/bouncer-secret-id"
 jq -r '"The secret_id lasts \(.data.secret_id_ttl / 86400) days."' "$HANDOVER/secret-id.json"
 shred -u "$HANDOVER/secret-id.json")
scp "$HANDOVER/bouncer-role-id" "$HANDOVER/bouncer-secret-id" admin@bouncer.example.com:
shred -u "$HANDOVER"/* && rmdir "$HANDOVER"

Expected result: The secret_id lasts 90 days., or fewer if you kept a lower limit.

If you run the kit on the Bouncer server itself, leave out scp and shred, and install the files from "$HANDOVER" in step 3.

Write down when the secret_id expires. When it does, the server can no longer log in to OpenBao. Replacing the secret_id explains how to renew it.

Keep the kit's resources file next to the kit's scripts. The emergency stop needs it.

Step 3: the config and the secret files

Make the folders on the Bouncer server:

sudo install -d -m 0755 /etc/bouncer /etc/bouncer/config
sudo install -d -m 0700 -o 10001 -g 10001 /etc/bouncer/secrets

User ID 10001 is the user the server runs as inside its container. It doesn't need to exist on the host.

Install the three secret files, readable only by that user. They are mounted read-only into the container at /run/secrets/<name>, and never put into an environment variable or the image.

# The two files from step 2d, in your home folder:
sudo install -m 0400 -o 10001 -g 10001 ~/bouncer-role-id ~/bouncer-secret-id /etc/bouncer/secrets/
shred -u ~/bouncer-role-id ~/bouncer-secret-id

# The database password: a random one you never need to type.
head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n' |
  sudo install -m 0400 -o 10001 -g 10001 /dev/stdin /etc/bouncer/secrets/bouncer-db-password

With rootless Podman, user 10001 inside the container is a different user outside it. Make the files yours, then hand them over inside Podman's user namespace:

sudo chown -R "$USER": /etc/bouncer/secrets
podman unshare chown -R 10001:10001 /etc/bouncer/secrets

Now the config file. Start from the example and change every value marked CHANGE:

cd ~/bouncer/deploy/compose
sudo install -m 0644 bouncer.yaml.example /etc/bouncer/config/bouncer.yaml
sudo $EDITOR /etc/bouncer/config/bouncer.yaml

The settings to change first:

  • instance.id: a short name such as example-home. Pick it once and never change it: it goes into every signed approval.
  • instance.url: the HTTPS address people's apps will use, for example https://bouncer.example.com. It must match what your reverse proxy serves (TLS and networking).
  • people: the people who approve, one entry each.
  • openbao.address: your OpenBao, as both the server and your requesters reach it. If its certificate isn't publicly trusted, save the CA certificate as /etc/bouncer/config/openbao-ca.pem and set ca_file: /etc/bouncer/openbao-ca.pem (the config folder is mounted at /etc/bouncer inside the container).
  • resources: one entry per resource, with the same IDs and KV paths as the role kit's resources file.
  • pairing: leave allow_software_keys: false. Add allow_user_verified_keys: true if anyone will approve from an iPhone, and allow_webauthn_keys: true if anyone will approve from a Windows PC with Windows Hello. Both are off by default, and without them those devices can't approve (Pair a device).
  • defaults.durations.always: set it to false, and take always out of defaults.durations.presets. The example file allows standing grants, grants with no end time, and the Bouncer project hasn't decided their policy yet (Approvals and access duration).
  • Leave push: null for now (Push notifications).

Configure the server explains each section, and Resources and policy explains what each resource setting does.

Step 4: build the image

If you installed from a release download, skip this step. You loaded the image in step 1a, and .env names it.

From the source:

cd ~/bouncer/deploy/compose
docker compose build --build-arg BOUNCER_VERSION="$(git describe --tags --always)" \
  --build-arg BOUNCER_REVISION="$(git rev-parse HEAD)"

This makes the image localhost/bouncer-server:local. On a machine with little memory, add --build-arg BUILD_JOBS=1. The build downloads two base images (Rust, and Debian for the runtime) and the crates in Cargo.lock, and nothing else. Both base images are pinned by digest.

With Podman, build from the repository root instead:

podman build --format docker -f deploy/compose/Dockerfile -t localhost/bouncer-server:local .

--format docker keeps the image's health check.

Step 5: start it

docker compose up -d --wait --wait-timeout 120
docker compose ps                  # both services "healthy"
docker compose logs bouncer        # look for "bouncer-server is up"
curl -s http://127.0.0.1:8080/v1/health

--wait waits for the containers' health checks, for up to 120 seconds. If it fails or times out, inspect the logs and health checks before continuing. A running container alone does not mean start-up has finished. If the log shows OpenBao is sealed or refusing Bouncer's login, fix that (When Bouncer is unavailable), then check health again.

With Podman, start the stack and use a bounded HTTP retry for the health check instead of Docker Compose's wait flags:

podman-compose up -d
podman-compose ps
podman-compose logs bouncer
curl --fail --silent --show-error --retry 24 --retry-delay 5 \
  --retry-connrefused --retry-max-time 120 --max-time 5 \
  http://127.0.0.1:8080/v1/health

Expected result: the health answer names your instance and the server version you installed. This example is from our 0.5.0 test run, so your version will differ. It shows the shape of the answer; newer servers add fields:

{"status":"ok","instance":{"id":"example-home","name":"Example home","url":"https://bouncer.example.com","contract":"bouncer.v1","version":"0.5.0+27","android_key_attestation":true,"credential_types":true},"server_time":"2026-11-15T10:00:00Z"}

At start-up the server connects to PostgreSQL, runs migrations, checks the config, creates a human requester for each person, and checks its OpenBao login and token roles. Invalid config, a database error or an OpenBao login with the wrong powers stops start-up. From 0.5.6, if OpenBao is sealed, unreachable or refuses the AppRole login, the server keeps running, answers 503 (backend_sealed, backend_unreachable or backend_auth_failed) and issues nothing. Earlier servers, such as 0.3.8, can exit and restart instead. Troubleshooting lists the messages. A healthy answer doesn't prove every resource can be issued, so make the test request in Next steps, step 3.

Next steps

  1. Put HTTPS in front of the server.

  2. Create requesters and pair your phone.

  3. Try a request from a requester machine (Integrate):

    bouncer request prod-db-password --for 15m --reason "First test" --wait   # approve on the phone
    bouncer exec prod-db-password --env PASSWORD=password -- sh -c 'test -n "$PASSWORD" && echo "got it"'
    

    This example assumes the resource has a field named password. Use the actual field name with --env; for the OpenBao test secret whose field is value, use --env PASSWORD=value.

  4. Run the kill switch once, so you know it works before you need it:

    docker compose exec bouncer bouncer-admin revoke --all
    

    It asks you to type yes, then ends every grant, cancels every pending request and asks OpenBao to revoke every token Bouncer issued. Check its report for any revoke it couldn't confirm.

  5. Schedule backups.

How this was checked

Steps 1 to 5 were run in our first test run, against a fresh OpenBao 2.7.2 and with Docker, with made-up names and secrets. In a second run, against a new OpenBao set up as in OpenBao for Bouncer, we ran steps 2a to 2d again, including the lifetime check in 2d: the mount's limit read 2764800 (32 days) until we raised it, and then the secret_id lasted 90 days. The scp was replaced by a local copy. The Podman commands in step 5 weren't run; they are the same commands through podman-compose.

The earlier 0.5.4 download instructions are checked against source only; no transcript of that installation is retained. On 17 November 2026, a fake-data test followed the release-download installation with a real OpenBao sandbox using 0.5.6, then upgraded and rolled back from 0.5.5. This did not test production or physical devices.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).