How to Configure HashiCorp Vault as a Secret Manager in Coolify

This article shows how to connect HashiCorp Vault to Coolify. It shows how to create a KV v2 secret, a read-only policy, and a token. It also shows how to use the secret in an application.

DevOps

Coolify can keep environment variables for each resource. You can also keep the values in HashiCorp Vault. Then Coolify reads the values from Vault during deployment.

This method does two things:

  • You change a secret in one location.
  • The secret value is not in the Coolify database.

This article shows how to connect Vault to Coolify and how to use a Vault secret in an application.

Create the secret in Vault

If you do not have a KV v2 secrets engine, enable one:

  • Mount: kv
  • Secret path: coolify

Add the key-value pairs to kv/coolify. Do not add the values to Coolify.

Create the policy

Open Access → Policies and create an ACL policy with the name read_coolify:

path "kv/data/*" {
  capabilities = ["read"]
}

path "kv/metadata/*" {
  capabilities = ["read", "list"]
}

path "auth/token/lookup-self" {
  capabilities = ["read"]
}

path "auth/token/renew-self" {
  capabilities = ["update"]
}

This policy allows read access to all secrets in the kv mount. If other users can access the Vault, limit the paths to one secret.

The token does not include the default policy. For this reason, Coolify cannot validate the token without the lookup-self rule. The renew-self rule is only for renewable tokens. You can remove it for this procedure.

Create the token

Open Operational Tools → API Explorer and send this request:

POST /v1/auth/token/create

Use this request body:

{
  "policies": ["read_coolify"],
  "ttl": "768h",
  "renewable": false,
  "no_default_policy": true
}

Copy auth.client_token from the response. Vault shows this value one time only.

768h is 32 days. Vault can set a shorter lifetime if max_ttl is lower. Read the token lifetime in the response.

The token is not renewable. When the token expires, deployments that use the secret fail. Set a reminder before the expiration date.

Add the integration in Coolify

Open Keys & Tokens → Integration Tokens and select New token. Select HashiCorp Vault as the provider.

  • Base URL: the Vault URL, for example https://vault.example.com. Do not add /v1.
  • Vault token: the token from the previous step.
  • Namespace: only for Vault Enterprise or HCP Vault.

Select Validate and add. If the validation fails, check the policy. Make sure that the policy contains the lookup-self rule. Also, the token can be older than the policy.

Use the secret in a resource

Open the application and select Environment Variables. In Secret manager, select the integration.

  1. Set Mount to kv.
  2. Set Secret path to coolify.
  3. Select Browse keys.
  4. Add the keys that you need, or import all keys.

Coolify creates a reference for each key:

API_KEY={{vault.API_KEY}}

Use kv as the mount and coolify as the path. Do not use /v1/kv/data/coolify. That value is an HTTP API path.

Note these points:

  • Coolify reads the values during deployment or restart. Coolify does not keep the values in its database. Coolify does not show the values in the deployment log.
  • If you change a value in Vault, deploy or restart the resource again. For runtime variables, do a restart. For build-time variables, do a full deployment.
  • One resource can use one secret manager source.

This procedure takes approximately 20 minutes. After the configuration, you change a secret one time in Vault and deploy the resource again.

Note: This article was dictated and refined with the help of AI.