Getting Started with HashiCorp Vault and Docker Compose (Part 1)

HashiCorp Vault is a tool for securely managing secrets, like API keys, passwords, or database credentials. For example, if your app needs a database password, Vault can store it encrypted and control who can access it. This Set up a simple Vault instance to manage secrets in development modeguide is the first in a series to help beginners explore Vault using Docker Compose, a tool that simplifies running containerized applications. In Part 1, you’ll set up a minimal Vault instance in development mode to store and retrieve secrets. Future parts will cover persistent storage, clustering, and advanced features like auto-unseal.

What is HashiCorp Vault?

Vault securely stores and manages sensitive data, called secrets, and controls access to them. Key features include:

• Secrets storage: Safely store API keys, passwords, or certificates.

• Access control: Define who or what can access secrets using policies.

• Dynamic secrets: Generate temporary credentials (e.g., for databases), which we’ll explore in later parts.

Running Vault with Docker Compose is perfect for beginners, as it simplifies setup and lets you focus on learning Vault’s basics.

Prerequisites

Before starting, ensure you have:

• Docker (version 20.10 or later). Install from Docker’s guide.

• Docker Compose (version 2.0 or later). See Docker Compose installation.

• Vault CLI (optional, for CLI access). Download from releases.hashicorp.com/vault or use a package manager (e.g., brew install vault on macOS).

• A text editor (e.g., VS Code).

• Commands are tested on Linux/macOS; Windows users may need to use set instead of export for environment variables (see below).

⚠️ Important: Dev Mode Warning

Warning: Never use Vault dev mode for production workloads. All secrets are lost on restart, and security is minimal. Dev mode is only for local testing and learning.

Setting Up Vault with Docker Compose

Let’s create a simple Vault setup using Docker Compose. This configuration runs Vault in development mode, which uses in-memory storage and auto-unseals (no manual key entry). It’s ideal for testing but not suitable for production, as secrets are lost on restart.

Step 1: Create the Docker Compose File

Create a file named docker-compose.yml in a new directory (e.g., vault-docker):

services:
  vault:
    image: hashicorp/vault:latest
    container_name: vault
    ports:
      - "8200:8200"
    environment:
      - VAULT_DEV_ROOT_TOKEN_ID=myroot
      - VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200
    cap_add:
      - IPC_LOCK
    command: vault server -dev

Key Notes:

• VAULT_DEV_ROOT_TOKEN_ID=myroot: Sets a root token for testing. Change it for security.

• cap_add: [IPC_LOCK]: Prevents Vault from swapping sensitive data to disk.

• Port 8200 is exposed for Vault’s web UI and API.

Step 2: Start Vault

1. Open a terminal, navigate to the vault-docker directory, and run:

docker compose up -d

The -d flag runs the container in the background.

2. Verify the container is running:

docker ps

You should see a vault container on port 8200.

Step 3: Access Vault

• Web UI:
  Open http://localhost:8200/ui (or http://127.0.0.1:8200/ui if localhost is blocked) in your browser. Log in with the token myroot. You can create, view, and manage secrets visually.

• CLI:
  You can authenticate to Vault using one of two methods:

  Option 1: Use vault login (recommended for CLI use)

    vault login myroot
  

  This command authenticates you and securely stores your token in a local helper file (usually ~/.vault-token). You won’t need to provide the token again for future CLI commands.

  Option 2: Set the VAULT_TOKEN environment variable (useful for scripts or temporary sessions)

  On Linux/macOS:

    export VAULT_ADDR=http://localhost:8200
    export VAULT_TOKEN=myroot
    vault status
  

  On Windows (Command Prompt):

    set VAULT_ADDR=http://localhost:8200
    set VAULT_TOKEN=myroot
    vault status
  

  This method makes the token available only for your current shell session.

  What’s the difference?

  • vault login is best for daily CLI use: it stores your token securely and you don’t need to set it again.

  • Setting VAULT_TOKEN is great for scripts or temporary sessions, but less secure for long-term use.

• Store a secret:

    vault kv put secret/my-secret password=supersecret
  

• Retrieve it:

    vault kv get secret/my-secret
  

Step 4: Stop Vault

To stop the container:

docker compose down

To remove all containers, networks, and volumes for a clean slate:

docker compose down --volumes

Note: In development mode, secrets are lost when the container stops.

Troubleshooting

• Vault Not Accessible: Ensure the container is running (docker ps) and port 8200 is free (lsof -i :8200). Check your firewall settings.

• Login Fails: Verify the token is myroot and VAULT_ADDR is http://localhost:8200.

• Browser Blocks Localhost: Use http://127.0.0.1:8200/ui.

What’s Next?

You’ve set up a basic Vault instance and stored a secret! This development mode is great for testing, but it’s not secure for production. In Part 2, we’ll add persistent storage, manual unsealing, and a MySQL database for dynamic secrets. Future parts will cover clustering, auto-unseal, and load balancing.

Try these quick experiments:

• Store another secret in the web UI and retrieve it via CLI.

• Explore the Vault UI’s “Policies” tab to see how access control works.

Share your progress in the comments or join the HashiCorp Community Forum!

Resources

• HashiCorp Vault Documentation: vaultproject.io

• Docker Compose Documentation: docs.docker.com/compose

• HashiCorp Learn: Free Vault tutorials (learn.hashicorp.com)

Note: For questions or setup help, reach out, comment below or check the Vault documentation.