Gateway & SSL

Nanokit includes an integrated Caddy-based Gateway that automatically handles service discovery, reverse proxying, and SSL certificate management.

Overview

Every environment (local, stage, production) orchestrated by Nanokit receives a dedicated gateway container. This gateway is the only entry point exposed to the host/internet, ensuring your internal services remain isolated in the private nanokit-net network.

Configuration

Gateway settings are defined at the top level of nanokit.yml:


gatewayPort: 80         # HTTP port on host
gatewayHttpsPort: 443   # HTTPS port on host
gateway:
  https: true           # Enable/disable SSL (default: true)
  adminEmail: admin@example.com
  persistenceMode: global # storage strategy for certificates

Persistence Modes

SSL certificates and ACME account data need to be persisted to avoid Let’s Encrypt rate limits and ensure stability across deployments.

Mode	Path	When to use
`project`	`.nanokit/gateway/`	Default for local. Keeps data within the project folder.
`global`	`/var/lib/nanokit/gateway/`	Default for remote. Ensures certificates survive project updates and redeploys on a VPS.

Zero-Downtime Reloads

When you change your configuration or add a new service, Nanokit performs a Zero-Downtime Reload of the gateway.

Instead of restarting the container, Nanokit pushes the new configuration to the running Caddy instance via its internal Admin API. This ensures that:

Active connections are not dropped.
SSL certificates remain in memory.
There is no “gap” in service availability.

Automated HTTPS

Nanokit manages SSL differently based on the hostname:

Public Domains: If the host is a public domain (e.g., myapp.com), Caddy automatically provisions and renews certificates via Let’s Encrypt or ZeroSSL.
Local/Internal Domains: For .localhost, .local, or .stage domains, Nanokit configures Caddy as a local Certificate Authority (CA), providing trusted HTTPS for development.

Security Hardening

The gateway automatically injects modern security headers into all site blocks:

Strict-Transport-Security (HSTS)
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin

[!IMPORTANT] To use standard ports (80/443) on a Linux VPS, ensure that no other web server (like Nginx or Apache) is currently listening on those ports.