Environments & Overrides

Nanokit architecture is based on Environment-First Orchestration. The environments block allows you to override any global setting for specific contexts like local, stage, or production.

Deep Merge Strategy

Nanokit uses a Deep Merge logic to resolve the final configuration:

Global Spec: Load all properties from the top-level blocks.
Environment Sync: Merge the matching key from environments (e.g., local).
Conflict Resolution: Specific environment values always overwrite global values.

Overridable Blocks

Almost everything in the global config can be overridden per environment:

Block	Example Override
`infra`	Change provider from `aws` to `docker` for local dev
`runtimes`	Change global images or env vars per environment
`services`	Change port, host, commands, env vars per environment
`deploy`	Set different SSH targets per environment
`gatewayPort`	Use different ports for co-existing environments
`gatewayHttpsPort`	Same as above, for HTTPS
`secrets`	Environment-specific vault paths

Git Branch Mapping (`git`)

Nanokit can automatically associate Git branches with specific environments. This is essential for CI/CD pipelines and preview environment automation.


git:
  environments:
    main: production
    develop: stage
    "feature/*": preview

When running nkapp up without the -e flag, Nanokit detects the current Git branch and maps it to the corresponding target context defined here.

Environment-Level Properties

Property	Type	Description
`infra`	object	Override the infrastructure provider and settings
`services`	object	Override service-level properties (image, port, host, env, start, etc.)
`deploy`	object	Override deployment target and method
`gatewayPort`	number	Override the HTTP gateway port
`gatewayHttpsPort`	number	Override the HTTPS gateway port
`secrets`	object	Environment-specific secrets

Common Patterns

Local Development Override


services:
  web:
    runtime: node
    port: 3000
 
environments:
  local:
    infra:
      provider: docker           # Use Docker instead of AWS
    services:
      web:
        start: npm run dev       # Dev server instead of production build
        host: web.my-app.localhost
        env:
          NODE_ENV: development

Multi-Environment Staging


environments:
  stage:
    gatewayPort: 8080            # Different port to avoid conflicts
    gatewayHttpsPort: 8443
    infra:
      provider: docker
    services:
      web:
        host: web.my-app.stage
        port: 8100
    deploy:
      target: root@10.0.0.5
      sshKey: ~/.ssh/id_staging
      method: rsync
      prepare: npm install --prefer-offline

Disabling Services Per Environment


environments:
  stage:
    services:
      hub:
        instances: 0    # Don't deploy Hub to staging

Production with Public Domains


environments:
  production:
    infra:
      provider: digitalocean
    services:
      web:
        runtime: node
        host: https://my-app.com
    deploy:
      target: root@185.47.172.104
      sshKey: vault://infra/ssh#private_key
      method: rsync

Viewing the Resolved Config

Use the CLI to see the fully merged configuration for any environment:


nkapp config -e <env>

[!TIP] This is invaluable for debugging merge issues — it shows exactly what values Nanokit will use for a given environment.