Global Properties

These properties define the foundational identity and behavior of your Nanokit project.

Property Reference

Property	Type	Default	Description
name	string	—	Required. Project identifier. Used to prefix all Docker resources (nk-<name>-<env>-<service>).
version	string	—	Configuration schema version (e.g., 1.0).
gatewayPort	number	80	Host port for the integrated Caddy gateway (HTTP).
gatewayHttpsPort	number	443	Host port for the integrated Caddy gateway (HTTPS).
gateway.https	boolean	true	Enable/disable HTTPS on the gateway. Set to false if you handle TLS externally.
gateway.adminEmail	string	admin@<host>	Email for ACME (Let's Encrypt) registration.
gateway.persistenceMode	project | global	project (local) / global (remote)	Where to store SSL data. global uses /var/lib/nanokit/gateway.

name: my-awesome-app
version: "1.0"
gatewayPort: 8080
gatewayHttpsPort: 8443
gateway:
  adminEmail: admin@example.com
  persistenceMode: global

---

Naming Conventions

Nanokit uses the name to ensure resource isolation. All containers, volumes, and networks follow the pattern:

nk-[project]-[env]-[service]

For example, with name: nanokit:

Resource	Name
Local docs service	nk-nanokit-local-docs
Stage website service	nk-nanokit-stage-website
Local gateway	nk-nanokit-local-gateway
Shared volume	nk-nanokit-local-shared

---

Environment-Level Overrides

gatewayPort and gatewayHttpsPort can be overridden per environment to allow multiple gateways on different ports:

name: my-app
gatewayPort: 80

environments:
  stage:
    gatewayPort: 8080
    gatewayHttpsPort: 8443

Tip. This lets you run local and stage environments simultaneously on the same Docker host without port conflicts.