Self-Hosting OpenBao on Ubuntu: TLS, Raft Storage & Backups

Make it executable:

Tips: If you prefer not managing certificates yourself, you can put Caddy or another reverse proxy in front, set the listener to 127.0.0.1:8200 with tls_disable = true, and let the proxy handle TLS automatically. Either way, keep port 8200 blocked from the public internet.

At this point, use your desired text editor to create the systemd unit file:

Add:

Disable swap, then enable and start the service:

A healthy log shows the listener starting on port 8200 and the node waiting to be unsealed. This sealed state is normal, unlike dev mode, where it unseals itself automatically.

Point the CLI to your TLS endpoint and initialize the cluster. This is the most important step of self-hosting OpenBao on Ubuntu. It generates the unseal keys and root token that control access to everything else.

Save all five unseal key shares and the root token somewhere offline and encrypted. Losing them means losing access to every secret stored on the node.

OpenBao starts sealed by default. It can find its data but cannot decrypt it until you provide enough unseal keys. Use three of your five unseal keys, entering them one at a time:

Log in with the root token and confirm the node is healthy:

Manually entering three unseal keys after every reboot is not practical. A reboot can leave OpenBao offline until someone unseals it. Auto-unseal solves this by using a trusted external service to unseal OpenBao automatically.

Here are the auto-unseal methods you can use:

With Auto-Unseal, OpenBao gives you recovery keys instead of normal unseal keys. Recovery keys can help with tasks like regenerating the root token, but they cannot decrypt OpenBao if your KMS, HSM, or Transit server is unavailable.

For a self-hosted setup, you can run a small second OpenBao instance as a Transit auto-unseal server for your main OpenBao server.

Add the seal configuration only after choosing your Auto Unseal method. For example, a Transit seal pointed at a second instance:

Moving from normal unseal keys to Auto Unseal needs short downtime. Take a fresh backup first and plan it as a maintenance task.

With the node unsealed, turn on the KV v2 engine and write a test secret:

Write a least-privilege policy so applications never touch the root token. Create app-readonly.hcl:

Add:

Apply it and enable an auth method for machines or humans to log in with:

For human access, use userpass or OIDC/JWT login instead of sharing static tokens. Policies and auth methods let Docker Compose, K3s, and ArgoCD access only the secrets they need without hardcoding credentials.

Raft stores all OpenBao data, so a Raft snapshot is a full server backup. You do not need to back up a separate database. Start by creating a manual snapshot:

Create a backup token that can only manage snapshots; never use the root token. Then use cron to run the backup every day:

Add:

Copy .snap backups to a different location, such as S3 storage, another server, or a backup VPS. A backup on the same server is useless if that server or disk fails. Before storing real secrets, make sure you have verified off-server backups.

A backup is only reliable if you have tested restoring it. Test recovery on the same server or on a separate test server:

With an empty Raft data folder, OpenBao starts as a new and uninitialized server. Initialize and unseal it first, then restore your snapshot:

After the restore completes, confirm your earlier secret and policies came back exactly as they were:

If both commands show the expected data, your backup and recovery process works. This proves you can restore OpenBao successfully after a failure.

You now have OpenBao running with Raft storage, TLS, limited-access policies, and tested backups. Monitor it, keep off-server backups, install updates, and plan Auto Unseal before an unexpected reboot.

We hope you enjoy this guide. 

For more details about Raft storage, backups, and cluster management, see the official OpenBao documentation.