Local Encrypted Vault

Integration Guide

Local Mode - Development with Encrypted Vault

Use DSO's built-in encrypted vault for development, testing, and air-gapped environments. Zero external dependencies, AES-256-GCM encryption, perfect for getting started with DSO.

Why This Integration?

Developers need a simple way to manage secrets locally without cloud accounts or external dependencies. Getting started with Docker Secret Operator should be fast and straightforward. Traditional Local Development Problems: - Hardcoded secrets in docker-compose.yaml (committed to git) - .env files exposed via docker inspect - No encryption for local development - Difficult to migrate to production providers - No way to practice secret management patterns Why DSO Local Mode Matters: Built-in encrypted vault lets you practice DSO patterns immediately. No cloud setup needed. When ready for production, simply switch providers—same dso.yaml format, same injection mechanism.

Architecture

Overview

Local Mode provides a secure, development-friendly secret system: 1. Trust Boundary: Local file encryption (AES-256-GCM) 2. Secret Lifecycle: Create with CLI → Encrypt at rest → Inject at runtime 3. Persistence: Encrypted only (plaintext never on disk) 4. Rotation: Manual update and redeploy 5. Perfect For: Learning DSO, testing patterns, air-gapped environments

Initialize Vault

Create encrypted vault at ~/.dso/vault.enc with master key derivation.

Create Secrets

Use CLI to add secrets to local vault with AES-256-GCM encryption.

Configure DSO

Define secrets in dso.yaml (no provider field needed for Local Mode).

Deploy Stack

Run docker dso up to inject secrets from encrypted vault into containers.

Setup Guide

Prerequisites

  • ✓Docker 20.10+ installed
  • ✓Docker Compose installed
  • ✓DSO v3.2+ installed (docker dso version)
  • ✓No cloud accounts needed
  • ✓No internet required (air-gapped ready)
1

Initialize Local Vault

Create encrypted vault for storing secrets.


# Initialize local vault
docker dso init

# This creates:
# - ~/.dso/vault.enc (encrypted secrets)
# - ~/.dso/ (master key)
2

Create Secrets

Add secrets to the encrypted vault.


# Create secrets using simple CLI
docker dso secret set DB_PASSWORD "your-secure-password"
docker dso secret set DB_USER "postgres"
docker dso secret set API_KEY "sk-1234567890abcdef"

# List all secrets (names only)
docker dso secret list

# Retrieve a secret (plaintext)
docker dso secret get DB_PASSWORD --reveal
3

Create dso.yaml

Configure DSO (no provider needed for Local Mode).


# dso.yaml - Local Mode configuration
# Note: No 'provider' field—Local Mode is default

secrets:
  - name: DB_PASSWORD
    inject: env

  - name: DB_USER
    inject: env

  - name: API_KEY
    inject: env
4

Create docker-compose.yaml

Define application stack with dso:// references.


version: "3.9"

services:
  app:
    image: python:3.11
    environment:
      - DB_PASSWORD=dso://DB_PASSWORD
      - DB_USER=dso://DB_USER
      - API_KEY=dso://API_KEY
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: dso://DB_PASSWORD
      POSTGRES_USER: dso://DB_USER
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
5

Deploy Stack

Start containers with secrets injected from local vault.


# Deploy
docker dso up -d

# Verify injection
docker logs app | grep DB_PASSWORD

# Verify zero-persistence
docker inspect app | grep DB_PASSWORD
# Should output nothing (secret not persisted)
6

Test Secret Update

Update secret and redeploy to see rotation.


# Update secret in vault
docker dso secret set DB_PASSWORD "newpassword123"

# Redeploy to apply new secret
docker dso down
docker dso up -d

# Verify new secret
docker logs app | grep DB_PASSWORD
# Should show new value

Security Benefits

✓Encrypted Storage: AES-256-GCM encryption at ~/.dso/vault.enc
✓Zero Persistence: Plaintext never written to disk
✓Machine-Locked: Master key derived from system (not portable)
✓User-Private: Secrets only readable by owning user (chmod 600)
✓No Network: Completely offline capable
✓Development-Safe: Perfect for learning and testing

Common Problems & Solutions

Vault not initialized
Run: docker dso init
This creates ~/.dso/vault.enc and master key.
Secret not found error
1. List existing secrets: docker dso secret list
2. Create missing secret: docker dso secret set SECRET_NAME "value"
3. Verify dso.yaml uses exact secret name
Secret visible in docker inspect
Make sure docker-compose.yaml uses dso:// references:
❌ WRONG: environment: DB_PASSWORD=mysecret
✅ CORRECT: environment: DB_PASSWORD=dso://DB_PASSWORD
Permission denied on vault file
Fix file permissions:
chmod 600 ~/.dso/vault.enc
chmod 700 ~/.dso/
Vault lost after machine restart
Vault is machine-specific and can't be recovered.
Lesson: Backup ~/.dso/vault.enc regularly.
To recover: Re-initialize and re-create all secrets.

Frequently Asked Questions

Can I use Local Mode in production?

No. Local Mode is for development only. For production, use AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault. They provide audit logging, high availability, and proper secret management.

How do I migrate from Local Mode to AWS/Azure?

Copy your secrets to the cloud provider, update dso.yaml with provider settings, and redeploy. The docker-compose.yaml and secret injection mechanism remain the same.

Is the vault encrypted?

Yes. Secrets stored in ~/.dso/vault.enc are encrypted with AES-256-GCM. The master key is derived from your system and not stored as plaintext.

Can I share the vault file with team members?

No. The vault is locked to your machine. The master key is derived from your system. To share secrets, use a cloud provider or self-hosted Vault instead.

What happens if I delete ~/.dso/vault.enc?

All secrets are lost (unless you have a backup). Re-initialize with docker dso init and re-create all secrets.

Is Local Mode the same as Docker secrets?

No. Docker secrets are for Swarm mode. Local Mode is DSO's development feature using encrypted local storage.

Can I use Local Mode in containers running on remote servers?

No. Vault is machine-specific. For remote deployments, use cloud providers (AWS/Azure/Vault) instead.

Related Pages

Ready to Deploy?

Follow the setup guide above to integrate Local Encrypted Vault with Docker Secret Operator.

DSO DocumentationLocal Encrypted Vault Docs