# 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](https://docs.docker.com/get-docker/).
    
* **Docker Compose** (version 2.0 or later). See [Docker Compose installation](https://docs.docker.com/compose/install/).
    
* **Vault CLI** (optional, for CLI access). Download from [releases.hashicorp.com/vault](https://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`):

```python
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:
    

```python
docker compose up -d
```

The `-d` flag runs the container in the background.

2. Verify the container is running:
    

```python
docker ps
```

You should see a `vault` container on port `8200`.

## **Step 3: Access Vault**

* **Web UI**:  
    Open [http://localhost:8200/ui](http://localhost:8200/ui) (or [http://127.0.0.1:8200/ui](http://127.0.0.1:8200/ui) if localhost is blocked) in your browser.[  
    ](http://127.0.0.1:8200/ui)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)**
    
    ```bash
    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**:
    
    ```bash
    export VAULT_ADDR=http://localhost:8200
    export VAULT_TOKEN=myroot
    vault status
    ```
    
    On **Windows (Command Prompt)**:
    
    ```bash
    set VAULT_ADDR=http://localhost:8200
    set VAULT_TOKEN=myroot
    vault status
    ```
    
    This method makes the token available only for your curre[nt shell session.](http://localhost:8200/ui)
    
    **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:**
    
    ```bash
    vault kv put secret/my-secret password=supersecret
    ```
    
* **Retrieve it:**
    
    ```bash
    vault kv get secret/my-secret
    ```
    

## **Step 4: Stop Vault**

To stop the container:

```bash
docker compose down
```

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

```bash
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](https://discuss.hashicorp.com/)!

## **Resources**

* **HashiCorp Vault Documentation**: [vaultproject.io](https://www.vaultproject.io/)
    
* **Docker Compose Documentation**: [docs.docker.com/compose](https://docs.docker.com/compose)
    
* **HashiCorp Learn**: Free Vault tutorials ([learn.hashicorp.com](https://learn.hashicorp.com/))
    

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