Multi-Tenancy Orchestration

Nanokit is designed to support the coexistence of multiple environments (e.g., staging, test, dev) on the same infrastructure node (VPS or local machine). This capability, defined as Multi-Tenancy, allows you to optimize hardware costs by logically isolating resources.

Isolation Mechanisms

Isolation between environments on the same node is based on three pillars:

1. Docker Labels

Every resource created by Nanokit (containers, volumes, networks) is marked with the nk-env label. The Reconciler uses this tag to filter operations:

• nkapp up -e staging will only modify containers with nk-env: staging.
• production containers will remain untouched even if they reside on the same Docker daemon.

2. Network Sandboxing

For each environment, Nanokit creates a dedicated Docker network (e.g., nanokit-net-staging).

• Services within the same environment can communicate via hostname (e.g., api talks to db).
• Services from different environments cannot communicate with each other internally, ensuring that a bug in staging cannot corrupt the production database.

3. Resource Naming

Container names are prefixed with the project name and the environment: nk-[project]-[env]-[service] (e.g., nk-myapp-staging-web).

Conflict Management

The main challenge of multi-tenancy on a single node is the collision of shared resources (host ports and file system).

Port Collisions

If two environments attempt to map the same host port (e.g., 80:80), Docker will fail. Solution: Never expose service ports directly on the host. Use Nanokit’s integrated gateway.

Ingress Gateway (Caddy)

Nanokit starts a single Gateway container (Caddy) that acts as a Reverse Proxy.

• The Gateway listens on standard ports 80 and 443.
• It routes traffic based on the Hostname (SNI/Host Header).

Example nanokit.yml configuration:

environments:
  staging:
    services:
      api:
        host: api.stage.myapp.com  # Reachable via Gateway
  production:
    services:
      api:
        host: api.myapp.com        # Reachable via Gateway on the same node

Multi-Environment VPS Setup

To configure two environments on the same VPS, simply point to the same SSH target but differentiate the application hosts.

name: my-app
 
environments:
  staging:
    deploy:
      target: root@1.2.3.4
    services:
      web:
        host: staging.myapp.com
        env:
          DEBUG: "true"
 
  production:
    deploy:
      target: root@1.2.3.4 # Same IP as staging
    services:
      web:
        host: app.myapp.com
        env:
          DEBUG: "false"

Management Commands:

• nkapp deploy -e staging: Updates only the staging version on the VPS.
• nkapp deploy -e production: Updates the production version on the same VPS.

Best Practices

1. Separate Databases: Even if on the same node, use separate database instances (different containers) or at least different databases/schemas to prevent cross-environment data leaks.
2. Resource Limits: Set cpu and memory limits in nanokit.yml to prevent the staging environment from consuming all node resources, penalizing production.
3. Single Gateway: Nanokit automatically manages a single Gateway per node that aggregates routes from all detected environments.
4. Cleanup: Regularly use nkapp down -e [env] to remove no-longer-needed test environments and free up resources on the shared node.