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:

1. Global Spec: Load all properties from the top-level blocks.
2. Environment Sync: Merge the matching key from environments (e.g., local).
3. 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.