Chapter 2 / 28
Installing Vault Using Docker
HashiCorp Vault For Beginners7 min read
In this chapter, we’ll launch HashiCorp Vault using Docker in a way that persists all Vault data even after stopping the container.
To make this hands-on experience smoother, we’ve already prepared the Vault configuration file and data directory for you. You don’t need to write the configuration yourself—just follow the steps and you’ll be up and running in no time.
Step 1: Clone Pre-bundled Repo
All the required configuration files, Vault data directory structure, and chapter-wise example folders are already organized for you.
Before you continue, please clone the following GitHub repository, which contains everything you’ll need as we progress through the book:
git clone https://github.com/intekhabrizvi/vault-beginner.git
cd vault-beginner
Step 2: Launching Vault with Persistent Storage
We’ll run Vault using Docker and ensure it writes to a local folder (vault-beginner/vault-data/file) so the data survives across container restarts.
The pre-created configuration file is stored at vault-beginner/vault-data/config/vault.hcl location.
Use the following Docker command to start Vault:
docker run -d --rm \
-p 8200:8200 \
-v $(pwd)/vault-data/config:/vault/config \
-v $(pwd)/vault-data/file:/vault/file \
-v $(pwd)/vault-data/logs:/vault/logs \
-v $(pwd):/home/vault/vault-beginner \
--cap-add=IPC_LOCK \
--name vault-dev \
hashicorp/vault:latest server
Note: If you're on Windows, make sure to adjust the
"$PWD"path accordingly to point to the absolute path of thevault-beginnerrepo on your machine.
Explanation by Segment
| Part | Purpose |
|---|---|
docker run | This starts a new container instance from the specified Docker image. |
-d | Runs the container in detached mode, meaning it runs in the background. |
--rm | Automatically removes the container when it stops. This is useful for cleanup, but be careful — it deletes the container (not the data) once stopped. |
-p 8200:8200 | Maps port 8200 on your host to port 8200 inside the container. Vault uses port 8200 for its HTTP API and UI. |
-v $(pwd)/vault-data/config:/vault/config | Mounts the Vault config folder from your host into the container at /vault/config. This is where your vault.hcl file lives. |
-v $(pwd)/vault-data/file:/vault/file | Mounts the data storage folder for Vault’s persistent backend. This is where Vault saves secrets, tokens, leases, etc. |
-v $(pwd)/vault-data/logs:/vault/logs | Mounts a log directory so that Vault's logs can be persisted on your host for inspection. |
-v $(pwd):/home/vault/vault-beginner | Mounts the vault-beginner folder we just cloned inside the vault container. This will help you to execute the commands quickly. |
--cap-add=IPC_LOCK | Grants the container permission to lock memory using mlock. This prevents sensitive data from being swapped to disk. It’s an important security practice. |
--name vault-dev | Assigns a name to your container, making it easier to reference later with docker exec, docker logs, etc. |
hashicorp/vault:latest | Specifies the image to use. You’re using the latest official HashiCorp Vault Docker image. |
server | Tells Vault to run in server mode (as opposed to client mode). |
Step 3: Attach to the Vault Container
To interact with Vault CLI inside the container:
docker exec -it vault-dev /bin/sh
Now you’re inside the Vault container.
Step 4: Set the VAULT_ADDR Environment Variable
After the container starts, you will need to set the VAULT_ADDR environment variable. This environment variable is used by Vault clients (including the CLI) to point to the correct Vault server address. To set the VAULT_ADDR variable, run the following command inside the container.
export VAULT_ADDR=http://localhost:8200
Important Notes
- Persistence: The data is persisted because of the volume mounts. Even if the container is deleted (
--rm), the data will survive in the mounted host directories. - Memory Lock:
--cap-add=IPC_LOCKenablesmlock, but you still need to setdisable_mlock = falsein your Vault config (vault.hcl) to fully enable it. - Configuration: The config file (
vault.hcl) should be placed in thevault-data/configdirectory and it must define the storage backend (e.g., file) and the listener. - Accessing Logs: You can view Vault logs from the mounted folder
vault-data/logsor simply usedocker logs vault-dev. - Stopping the Container: Since
--rmis used, once you stop the container, it will be deleted. But the data will remain on your host via thevault-data/filefolder.
What’s Next?
In the next chapter, we’ll walk through how to initialize and unseal Vault from inside the container. We’ll also explain the purpose of the unseal keys, root token, and how Vault handles encryption from the moment you start using it.
Let’s move forward!