Hands-on Lab

How to Run OpenBao in Docker with Raft Storage

October 21, 2026 4 min

0 / 9

Cheat sheet

Found it useful? Don't miss the next lab

The video has captions and a transcript. Everything it shows is written out, step by step, below. Cheat sheet with every command

0:00 / 0:00

We create config/openbao.hcl with the guide's configuration. The storage "raft" block keeps the data in /openbao/file as node bao-1 and the listener serves port 8200 without TLS. The audit block declares the file audit log, and cluster_addr is mandatory with Raft even on a single node.

mkdir -p /root/openbao/config && cd /root/openbao && cat > config/openbao.hcl <<'EOF'
ui = true

storage "raft" {
  path    = "/openbao/file"
  node_id = "bao-1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

audit "file" "fichero" {
  options {
    file_path = "/openbao/logs/audit.log"
  }
}

api_addr     = "http://127.0.0.1:8200"
cluster_addr = "http://127.0.0.1:8201"
EOF

I did it

We write compose.yaml with the openbao/openbao:2.6.2 image and command: server, which avoids the in-memory dev mode. Port 8200 is bound to 127.0.0.1 only and the configuration is mounted read-only. Two named volumes hold the data: bao-datos for Raft and bao-logs for the audit log. The healthcheck queries /v1/sys/health every 30 s.

cd /root/openbao && cat > compose.yaml <<'EOF'
services:
  openbao:
    image: openbao/openbao:2.6.2
    command: server
    ports:
      - "127.0.0.1:8200:8200"
    environment:
      BAO_ADDR: "http://127.0.0.1:8200"
    volumes:
      - ./config:/openbao/config:ro
      - bao-datos:/openbao/file
      - bao-logs:/openbao/logs
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8200/v1/sys/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    restart: unless-stopped

volumes:
  bao-datos:
  bao-logs:
EOF

I did it

We check both files: the configuration declares Raft and its path, and docker compose config, which validates the YAML, resolves the 2.6.2 image and both volumes at /openbao/file and /openbao/logs.

cd /root/openbao && grep -nE 'storage|path|cluster_addr' config/openbao.hcl && docker compose config | grep -E 'image:|target: /openbao/(file|logs)'

What this proves

image: openbao/openbao:2.6.2 Compose resolves the image at the pinned version 2.6.2 Goal · you know the lab runs the same version as the guide, not whatever is newest on Docker Hub
target: /openbao/file the data volume mounts at /openbao/file, the path the Raft configuration asks for Goal · you confirm the Raft data will live on a volume and outlive the container

We reproduce the guide's error with two new volumes. The container runs as openbao; /openbao/file, which already exists in the image, inherits that owner, but /openbao/data stays owned by root and writing to it fails with Permission denied. That is why the Raft volume goes at /openbao/file.

docker pull -q openbao/openbao:2.6.2 >/dev/null && docker run --rm --entrypoint sh -v /openbao/file -v /openbao/data openbao/openbao:2.6.2 -c 'id -un; stat -c "%U:%G %n" /openbao/file /openbao/data; touch /openbao/data/vault.db'

I did it

We start OpenBao in the background with docker compose up -d. Compose creates the network and both volumes and starts the container. The server begins sealed and uninitialised: it has somewhere to store data, but no key exists yet.

cd /root/openbao && docker compose up -d

I did it

We wait for the API to answer and check three things. The startup log says Storage: raft (HA available) and version 2.6.2. /v1/sys/health returns 501, the code for an uninitialised server, and /openbao/file belongs to openbao:openbao.

cd /root/openbao && for i in $(seq 1 60); do [ "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8200/v1/sys/health)" = 501 ] && break; sleep 2; done; docker compose logs openbao | grep -E 'Storage:|Version:'; curl -s -o /dev/null -w 'sys/health: HTTP %{http_code}\n' http://127.0.0.1:8200/v1/sys/health; docker compose exec openbao stat -c '%U:%G %n' /openbao/file

What this proves

Storage: raft (HA available) the server started with the Raft backend from the configuration Goal · you confirm OpenBao did not fall back to the in-memory dev mode
sys/health: HTTP 501 the health API answers 501, an uninitialised server Goal · you know the service is listening and the next step is to initialise it
openbao:openbao /openbao/file the data volume belongs to the openbao user Goal · you check Raft can write to its volume, unlike at /openbao/data

We initialise OpenBao with bao operator init, 5 keys and a threshold of 3 as in the guide. With -format=json the output goes to init.json, and jq extracts the keys to unseal-keys and the root token to root-token, with mode 600. They are throwaway keys inside a container we destroy at the end; on a real server you copy them off now, because OpenBao never shows them again.

cd /root/openbao && docker compose exec -T openbao bao operator init -key-shares=5 -key-threshold=3 -format=json > init.json && jq -r '.unseal_keys_b64[]' init.json > unseal-keys && jq -r .root_token init.json > root-token && chmod 600 init.json unseal-keys root-token

I did it

We check the result without printing any secret: both files exist with mode 600, init.json declares 5 keys with a threshold of 3, the root token carries OpenBao's s. prefix and bao status shows Initialized true, Sealed true and Unseal Progress 0/3.

cd /root/openbao && ls -l unseal-keys root-token && jq '{unseal_shares, unseal_threshold}' init.json && echo "token prefix: $(cut -c1-2 root-token)" && docker compose exec openbao bao status | grep -E 'Initialized|Sealed|Total Shares|Threshold|Unseal Progress'

What this proves

"unseal_threshold": 3 initialisation generated keys with a threshold of 3 Goal · you know how many keys you must gather to open OpenBao after every restart
token prefix: s. the root token starts with s., OpenBao's prefix, shown without revealing the rest Goal · you confirm the token is saved without exposing it on screen
Unseal Progress 0/3 the server is initialised but sealed, with 0 of 3 keys entered Goal · you see initialising is not enough: the data stays encrypted until you unseal

We unseal with 3 of the 5 keys, read from the file and passed as an argument because the lab has no keyboard. On a real server run bao operator unseal with no argument: it prompts for the hidden key and keeps it out of the history. After each key we filter the progress: 1/3, 2/3 and Sealed false.

cd /root/openbao && for k in $(head -n 3 unseal-keys); do docker compose exec -T openbao bao operator unseal "$k" | grep -E '^(Sealed|Unseal Progress)'; done

I did it

bao status exits with code 0 and confirms the unseal: Sealed false, Total Shares 5 and Threshold 3. Storage Type raft and HA Mode active show that bao-1 leads its single-node Raft cluster.

cd /root/openbao && docker compose exec openbao bao status

What this proves

Sealed false the server is unsealed Goal · you know OpenBao now decrypts its data and can serve requests
Storage Type raft the storage in use is Raft Goal · you confirm secrets will go to the Raft volume, not to memory
HA Mode active the node is the active one in its cluster Goal · you see the single node has already won the Raft leader election

We export BAO_TOKEN from the root-token file and -e BAO_TOKEN passes it into the container without typing it on the command. We enable kv-v2 at secret/ and store app/db with user=app; with password=- the test value changeme comes in on standard input. The loop retries the put if OpenBao still answers Upgrading from non-versioned to versioned data, the problem the guide describes.

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao secrets enable -path=secret kv-v2 && for i in $(seq 1 10); do printf '%s' changeme | docker compose exec -T -e BAO_TOKEN openbao bao kv put -mount=secret app/db user=app password=- && break; sleep 1; done

I did it

We read the secret with bao kv get. The real path is secret/data/app/db, with the data/ segment KV v2 adds. The metadata shows version 1 and the data returns user app and password changeme, the test value.

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao kv get -mount=secret app/db

What this proves

secret/data/app/db the secret lives under the KV v2 data path Goal · you know which path to put in your applications' read policies
version 1 this is version 1 of the secret Goal · you confirm the engine keeps versions and the next write will not erase this one
password changeme OpenBao returns the stored test value Goal · you check the full write and read cycle of a secret

We save a Raft snapshot with bao operator raft snapshot save to /tmp in the OpenBao container, copy it to the project directory with docker compose cp and delete the inner copy. It is a live copy: the server keeps serving requests.

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao operator raft snapshot save /tmp/bao.snap && docker compose cp openbao:/tmp/bao.snap ./bao.snap && docker compose exec openbao rm /tmp/bao.snap

I did it

We check the backup: bao.snap is a tar.gz with meta.json, state.bin, which holds the still-encrypted data, SHA256SUMS and SHA256SUMS.sealed. bao operator raft list-peers confirms bao-1 is the cluster's leader and voter.

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && ls -l bao.snap && tar -tzf bao.snap && docker compose exec -e BAO_TOKEN openbao bao operator raft list-peers

What this proves

state.bin the snapshot contains state.bin, the Raft data Goal · you know the backup carries the secrets, encrypted, ready to restore
SHA256SUMS.sealed it includes the checksums sealed with OpenBao's key Goal · you understand why restoring it needs the original unseal keys
leader bao-1 shows as leader of the Raft cluster Goal · you confirm the snapshot came from a healthy node leading the cluster

We check the status from outside: /v1/sys/health answers initialized true and sealed false with version 2.6.2. The Compose healthcheck, which queries that same path, marks the container healthy. /openbao/logs holds audit.log with the lab's requests.

cd /root/openbao && curl -s http://127.0.0.1:8200/v1/sys/health | jq '{initialized, sealed, version}' && for i in $(seq 1 45); do [ "$(docker inspect -f '{{.State.Health.Status}}' openbao-openbao-1)" = healthy ] && break; sleep 2; done; docker compose ps --format '{{.Name}} {{.Status}}'; docker compose exec openbao ls -l /openbao/logs

What this proves

"sealed": false the health API reports the server is unsealed Goal · you have the check your monitoring system would use
(healthy) Docker marks the container healthy Goal · you know other services can wait for OpenBao with depends_on and service_healthy
audit.log the audit log declared in the configuration exists Goal · you confirm every request is recorded from the first start

We clean up the lab: docker compose down -v removes the container, the network and the bao-datos and bao-logs volumes, and we delete init.json, unseal-keys, root-token and bao.snap. Without the keys, the snapshot could no longer be restored anywhere.

cd /root/openbao && docker compose down -v && rm -f init.json unseal-keys root-token bao.snap

I did it

We check no OpenBao container or volume is left and that /root/openbao only holds config and compose.yaml, with no key files.

cd /root/openbao && echo "openbao containers: $(docker ps -aq --filter name=openbao | wc -l)"; echo "openbao volumes: $(docker volume ls -q --filter name=openbao | wc -l)"; ls

What this proves

openbao volumes: 0 no OpenBao volume is left Goal · you leave the machine with no encrypted data or keys from the lab

Was this lab useful? Rate it:

Click to rate this post!

[Total: 0 Average: 0]

Video transcript

0:00 OpenBao in Docker, unsealed with 3 of 5 keys.
0:04 We write the guide's configuration:
0:07 Raft storage in /openbao/file and port 8200.
0:12 OpenBao in Docker with Raft:
0:14 unseal, store a secret, back it up.
0:17 Configure, start, initialise, unseal, store the secret and take the snapshot.
0:22 Compose pins version 2.6.2 and mounts the data on a volume.
0:28 We check it with docker compose config:
0:30 the pinned image is 2.6.2 and the data volume mounts at
0:35 /openbao/file.
0:38 A new volume inherits the owner only if the path exists in the image.
0:42 One of the problems I ran into:
0:45 at /openbao/data the volume belongs to root and OpenBao cannot write.
0:51 We start the service with docker compose up.
0:53 OpenBao starts sealed and uninitialised.
0:59 We check it:
0:59 the log shows Raft, the API answers 501, not initialised, and the volume
1:06 belongs to openbao.
1:09 The key splits into 5; any 3 rebuild it.
1:12 We initialise with 5 keys and a threshold of 3; jq saves them to files unseen.
1:18 We check it:
1:19 there are 5 keys and a token starting with s dot, and bao status says initialised,
1:25 sealed and progress 0 of 3.
1:30 We unseal with 3 keys:
1:32 1 of 3, 2 of 3, then Sealed false.
1:37 We check it with bao status:
1:39 Sealed false, raft storage and an active node.
1:42 OpenBao can now read its data.
1:49 We enable KV version 2 at secret and store a test secret.
1:58 We check it with kv get:
1:59 the secret is at secret/data/app/db, version 1, with the test user and
2:06 password.
2:10 A consistent copy of all the data, taken live.
2:13 The backup:
2:14 a Raft snapshot, copied out with docker compose cp.
2:20 We check it:
2:21 the snapshot is a tar with the data and its sealed checksums, and Raft lists bao-1
2:25 as leader.
2:31 A final status check:
2:32 the health API says sealed false, Docker marks the container healthy and the audit
2:37 log exists.
2:42 We clean up:
2:43 OpenBao, its volumes, the keys and the snapshot.
2:50 We check it:
2:51 no OpenBao container or volume is left, only the config and compose.yaml.

This lab reproduces on video the guide how to install OpenBao with Docker and Raft storage: the same openbao/openbao:2.6.2 image, the same configuration and the same commands, really executed in a throwaway container. If you want to run OpenBao in Docker to hold your services’ credentials, here you see every real output, from the first sealed bao status to the Raft snapshot.

What OpenBao is and why Raft

OpenBao is the fork of HashiCorp Vault that keeps the MPL 2.0 licence and Vault’s API, so the concepts in the article on HashiCorp Vault for secrets management apply the same way. Raft storage is built into the binary: it writes the encrypted data to a directory and needs no external database. The Raft backend documentation requires cluster_addr even on a single node.

Who owns the data volume

The image runs as the unprivileged openbao user, and Docker only copies that owner into a new volume when the path already exists in the image. That is why the volume goes at /openbao/file: at /openbao/data the directory stays owned by root and the lab shows the Permission denied. How a volume gets initialised is covered in the Docker volumes documentation and in the lab on how data persists in Docker.

Initialising and unsealing without showing the keys

bao operator init generates 5 unseal keys and the root token, and the lab writes them with jq to files with mode 600 so they are never printed. It then unseals with 3 of them. In the lab the keys go in as arguments because there is no keyboard; on your server run bao operator unseal with no argument, which prompts for the hidden key and keeps it out of the history. The full reference is in the bao operator init documentation.

What differs from the guide

The lab’s compose.yaml leaves out mem_limit and memswap_limit: the nested container it is recorded in does not delegate the cgroup v2 memory controller, and Docker rejects any memory limit. On your server keep both lines with the same value, as the guide explains, so the container’s swap stays at 0 and secrets never land on disk. The root token is not revoked here either, because the container is destroyed at the end.

For the other ways to handle secrets in containers there is the lab on managing secrets in Docker, and to ship snapshots off the server, the guide to restic for encrypted backups. The image and its tags are at openbao/openbao on Docker Hub, and the code in the OpenBao repository.

FAQ

Why does OpenBao start sealed after every restart?

Because with Shamir unsealing the key that decrypts the data is never stored on disk: it is rebuilt in memory from 3 of the 5 unseal keys. Until then bao status shows Sealed true and Unseal Progress 0/3, as in the lab, and the secrets stay encrypted.

Where do I mount OpenBao's Raft volume in Docker?

At /openbao/file. The image runs as the openbao user and Docker only copies that owner into a new volume when the path already exists in the image. On a path such as /openbao/data the directory stays owned by root and writing fails with Permission denied, as the lab shows.

Does a Raft snapshot store the secrets in clear text?

No. The file is a tar.gz with meta.json, state.bin, SHA256SUMS and SHA256SUMS.sealed, and state.bin keeps the data encrypted with OpenBao's key. That is why it only restores with the original unseal keys, which must be kept somewhere other than the snapshot.

Why does the first kv put fail right after enabling KV v2?

When you enable kv-v2, OpenBao prepares the versioned storage and for a moment answers Upgrading from non-versioned to versioned data. The guide hit it on one of its installs: wait a second and run the command again. The lab handles it with a loop of up to 10 attempts.

Cheat sheet

mkdir -p /root/openbao/config && cd /root/openbao && cat > config/openbao.hcl <<'EOF'
ui = true

storage "raft" {
  path    = "/openbao/file"
  node_id = "bao-1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

audit "file" "fichero" {
  options {
    file_path = "/openbao/logs/audit.log"
  }
}

api_addr     = "http://127.0.0.1:8200"
cluster_addr = "http://127.0.0.1:8201"
EOF

cd /root/openbao && cat > compose.yaml <<'EOF'
services:
  openbao:
    image: openbao/openbao:2.6.2
    command: server
    ports:
      - "127.0.0.1:8200:8200"
    environment:
      BAO_ADDR: "http://127.0.0.1:8200"
    volumes:
      - ./config:/openbao/config:ro
      - bao-datos:/openbao/file
      - bao-logs:/openbao/logs
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8200/v1/sys/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    restart: unless-stopped

volumes:
  bao-datos:
  bao-logs:
EOF

docker pull -q openbao/openbao:2.6.2 >/dev/null && docker run --rm --entrypoint sh -v /openbao/file -v /openbao/data openbao/openbao:2.6.2 -c 'id -un; stat -c "%U:%G %n" /openbao/file /openbao/data; touch /openbao/data/vault.db'

cd /root/openbao && docker compose up -d

cd /root/openbao && docker compose exec -T openbao bao operator init -key-shares=5 -key-threshold=3 -format=json > init.json && jq -r '.unseal_keys_b64[]' init.json > unseal-keys && jq -r .root_token init.json > root-token && chmod 600 init.json unseal-keys root-token

cd /root/openbao && for k in $(head -n 3 unseal-keys); do docker compose exec -T openbao bao operator unseal "$k" | grep -E '^(Sealed|Unseal Progress)'; done

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao secrets enable -path=secret kv-v2 && for i in $(seq 1 10); do printf '%s' changeme | docker compose exec -T -e BAO_TOKEN openbao bao kv put -mount=secret app/db user=app password=- && break; sleep 1; done

cd /root/openbao && export BAO_TOKEN=$(cat root-token) && docker compose exec -e BAO_TOKEN openbao bao operator raft snapshot save /tmp/bao.snap && docker compose cp openbao:/tmp/bao.snap ./bao.snap && docker compose exec openbao rm /tmp/bao.snap

cd /root/openbao && docker compose down -v && rm -f init.json unseal-keys root-token bao.snap

Found it useful? Don't miss the next lab

Subscribe to the newsletter

What OpenBao is and why Raft

Who owns the data volume

Initialising and unsealing without showing the keys

What differs from the guide

FAQ

Why does OpenBao start sealed after every restart?

Where do I mount OpenBao's Raft volume in Docker?

Does a Raft snapshot store the secrets in clear text?

Why does the first kv put fail right after enabling KV v2?

Cheat sheet