Intekhab Rizvi

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 the vault-beginner repo on your machine.

Explanation by Segment

PartPurpose
docker runThis starts a new container instance from the specified Docker image.
-dRuns the container in detached mode, meaning it runs in the background.
--rmAutomatically 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:8200Maps 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/configMounts 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/fileMounts the data storage folder for Vault’s persistent backend. This is where Vault saves secrets, tokens, leases, etc.
-v $(pwd)/vault-data/logs:/vault/logsMounts a log directory so that Vault's logs can be persisted on your host for inspection.
-v $(pwd):/home/vault/vault-beginnerMounts the vault-beginner folder we just cloned inside the vault container. This will help you to execute the commands quickly.
--cap-add=IPC_LOCKGrants 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-devAssigns a name to your container, making it easier to reference later with docker exec, docker logs, etc.
hashicorp/vault:latestSpecifies the image to use. You’re using the latest official HashiCorp Vault Docker image.
serverTells 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

  1. 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.
  2. Memory Lock: --cap-add=IPC_LOCK enables mlock, but you still need to set disable_mlock = false in your Vault config (vault.hcl) to fully enable it.
  3. Configuration: The config file (vault.hcl) should be placed in the vault-data/config directory and it must define the storage backend (e.g., file) and the listener.
  4. Accessing Logs: You can view Vault logs from the mounted folder vault-data/logs or simply use docker logs vault-dev.
  5. Stopping the Container: Since --rm is used, once you stop the container, it will be deleted. But the data will remain on your host via the vault-data/file folder.

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!