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

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:

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.