Deploying a Vault App

Introduction

Vault secures secrets, tokens, and encryption keys behind a single API. This guide shows how to containerize Vault with a file storage backend, persist data, and deploy it to Klutch.sh over HTTP.

Prerequisites

• GitHub repository containing your Dockerfile.
• Klutch.sh project ready in klutch.sh/app.
• Plan for initializing and unsealing Vault (e.g., recovery keys stored securely).

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM hashicorp/vault:latest

# Default Vault port
ENV VAULT_ADDR=http://0.0.0.0:8200
EXPOSE 8200

# Provide a local file backend and listener via VAULT_LOCAL_CONFIG
ENV VAULT_LOCAL_CONFIG='{
  "backend": {
    "file": { "path": "/vault/file" }
  },
  "listener": [{
    "tcp": {
      "address": "0.0.0.0:8200",
      "tls_disable": 1
    }
  }],
  "ui": true
}'

ENTRYPOINT ["vault", "server", "-dev=false"]

Required environment variables

• VAULT_LOCAL_CONFIG – JSON config defining storage and listener (example above).
• VAULT_ADDR – internal address (e.g., http://0.0.0.0:8200).
• Any extra listener/storage config you need (e.g., TLS settings if you terminate TLS at Vault).

Optional environment variables

• VAULT_API_ADDR – public URL, e.g., https://example-app.klutch.sh
• VAULT_CLUSTER_ADDR – for clustering if you scale.
• VAULT_LOG_LEVEL – e.g., info or warn.

Persistence

Vault file storage must be durable:

• Mount path: /vault/file
• Size: based on secret/data footprint and audit logs if enabled

Networking

• Protocol: HTTP
• Internal port: 8200
• Users and clients reach https://example-app.klutch.sh while Klutch.sh routes to port 8200 inside the container.

Health check (recommended)

curl -I http://localhost:8200/v1/sys/health

Deployment on Klutch.sh

1. Push your Dockerfile (and any custom config) to GitHub.
2. In klutch.sh/app, create a new app and select GitHub as the source.
3. Klutch.sh automatically detects the Dockerfile in the repository root.
4. Select HTTP traffic and set the internal port to 8200.
5. Add environment variables for VAULT_LOCAL_CONFIG, VAULT_ADDR, and any public addresses. Mark secrets and sensitive config as secrets in the dashboard.
6. Attach a persistent volume at /vault/file sized for your expected secret data and logs.
7. Deploy. After boot, initialize and unseal Vault, then store the unseal keys securely.

Verification

• Health endpoint:

  curl https://example-app.klutch.sh/v1/sys/health

• UI: open https://example-app.klutch.sh/ui after unsealing.

Next steps

• Add TLS termination (either at Klutch.sh or inside Vault) for production.
• Enable audit logging and store logs in a secure sink.
• Configure authentication methods (OIDC, AppRole) and set up periodic backups of the /vault/file volume.