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.

Naming convention

All Nanokit-provided and auto-generated environment variables use the full NANOKIT_ prefix (the short NK_ prefix is retired). Browser-exposed variables additionally carry the framework’s NEXT_PUBLIC_ prefix (e.g. NEXT_PUBLIC_NANOKIT_ENV). Standard third-party names — NODE_ENV, DATABASE_URL, JWT_SECRET, STRIPE_*, SMTP_*, … — are kept verbatim.

Standard Metadata

Every service container automatically receives these variables:

Transparent Secret Injection

When a service depends on a resource (like a database), Nanokit injects its connection details automatically, named NANOKIT_DB_<NAME>_URL (the database name upper-cased, non-alphanumerics → _).

For a database named postgres (referenced as db://postgres), Nanokit injects:

• NANOKIT_DB_POSTGRES_URL: the full connection string.

[!TIP] This works automatically through the depends_on block (and db:// references) 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

The service:// Scheme

Inside the env: block, you can use the service:// scheme to dynamically reference the host address of another service within the project. This is highly useful for pointing environment variables directly to peer container addresses (such as connecting an authentication service to a mail server, or an API gateway to a runtime endpoint).

services:
  api-auth:
    depends_on:
      - mail
    env:
      SMTP_HOST: "service://mail" # Resolves to the internal container host of the mail service

Nanokit automatically translates service://<service-name> into the exact, fully qualified container hostname for the active environment (e.g., nk-nanokit-local-mail or nk-nanokit-stage-mail), allowing containers to locate and communicate with each other dynamically on the private virtual network without hardcoding IPs or environment-specific names.

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.