Secrets & Environment Variables

Nanokit draws a clear line between configuration and secrets. Understanding this separation is key to building secure, team-friendly projects.

The Two Blocks: env vs secrets

services:
  api:
    env:
      LOG_LEVEL: info        # ✅ Non-sensitive — safe to commit
      NODE_ENV: production
 
    secrets:
      DB_PASSWORD:
        from: vault          # 🔐 Resolved at runtime

[!IMPORTANT] Values inside secrets: are never written to local state files in plain text. They are resolved fresh on every nkapp up, plan, or deploy run.

1. Built-in Environment Variables

Nanokit automatically injects metadata and connection strings into your services. You can use these variables in your code or reference them in other configuration files.

Standard Metadata

Every service container automatically receives these variables:

Transparent Secret Injection

When a service depends on a resource (like a database), Nanokit injects connection details using a standardized prefix.

For a database named main-db, Nanokit will inject:

• MAIN_DB_URL: The full connection string.
• MAIN_DB_USER: The username (if provided).
• MAIN_DB_PASSWORD: The password (if provided).

[!TIP] This works automatically through the depends_on block without any manual mapping.

2. Using Variables in Configuration

Nanokit supports standard environment variable expansion inside nanokit.yml and .env files.

YAML Expansion

You can use ${VARIABLE_NAME} or ${VARIABLE_NAME:-default_value} anywhere in your nanokit.yml.

services:
  api:
    image: "my-registry.com/${NANOKIT_PROJECT}:${VERSION:-latest}"
    env:
      DATA_DIR: "/data/${NANOKIT_SERVICE}"

The db:// Scheme

Inside the env: block, you can use the db:// scheme to explicitly request a database connection string. This is useful if you want to map a database URL to a specific variable name expected by your application (e.g., DATABASE_URL).

services:
  api:
    depends_on:
      - redis
    env:
      REDIS_CACHE_URL: "db://redis" # Resolves to the internal Redis URI

3. .env File Strategy

Nanokit loads environment variables hierarchically from your project root. Variables loaded here can be used for YAML expansion.

Priority Order (Highest to Lowest)

1. .env.local: Local overrides for developers (always Gitignored).
2. .env.<environment>: Environment-specific overrides (Gitignored).
3. .env: Global defaults (intended to be committed).

Best Practice

Keep your .env file clean and use it only for non-sensitive defaults that help other developers bootstrap the project. Never commit .env.local or .env.production.

4. Local & Process Secrets (Manual Mode)

Nanokit allows you to pull secrets from your host machine or CI/CD runner using the env:// scheme.

services:
  api:
    env:
      API_KEY: "env://STRIPE_API_KEY" # Pulls from your local shell environment

5. Vault Integration (Enterprise Mode)

For production-grade security, Nanokit integrates with HashiCorp Vault.

Connectivity Requirements

Set these variables on your machine to enable Vault resolution:

• VAULT_ADDR: https://vault.internal:8200
• VAULT_TOKEN: hvs.xxx...

Local Development Workflow

Secrets are not available locally by default. To bridge Cloud secrets to your local workspace, use:

nkapp secrets pull

This command resolves all URIs and writes them to .env.local, allowing your local services to run with real (or simulated) credentials safely.