nanokit.yml Reference

The nanokit.yml file is the central nervous system of your Nanokit project. It uses a declarative YAML syntax to define infrastructure, services, and multi-environment orchestration.

To make it easier to navigate, we've broken down the reference into modular sections:

---

🏗️ Global Properties

Manage project identity, versioning, and global networking defaults like gatewayPort.

🖥️ Infrastructure

Configure your cloud providers (Docker, AWS, Azure, GCP, DigitalOcean) and define instance roles, regions, and scaling strategies.

🚀 Global Runtimes

Centralize your images, environment variables, and provisioning steps once and reuse them across all services. Includes smart auto-discovery logic.

📦 Services & Provisioning

Define your application containers, environment variables, dependency graphs, and atomic provisioning hooks.

🗄️ Databases

Native integration with PostgreSQL, MySQL, MariaDB, MongoDB and Redis, featuring automated branching and sub-second volume cloning for local development.

⏰ Cron Jobs

Native, declarative task scheduling. Automate backups, cleanups, and background tasks with integrated support for Docker and cloud-native schedulers.

🌍 Environments & Overrides

Master the Deep Merge strategy to effortlessly manage settings for local, stage, and production.

🔐 Secrets & Env Variables

Understand the env vs secrets separation, define Vault references, and manage credential scoping across environments.

🌐 Networks

Define custom virtual networks, handle visibility (public/private), and attach to existing cloud VPCs.

💾 Volumes

Configure named persistent data volumes for stateful services and cross-replica data sharing.

🚀 Deployment Configuration

Configure target servers, SSH authentication, and synchronization methods (rsync or git) for remote orchestration.

🔄 Lifecycle Hooks

Automate prep and post-deployment tasks with container-native hooks like prestart, poststart, and prestop.

🛡️ Gateway & SSL

Deep dive into Caddy configuration, zero-downtime reloads, and custom domain management with automatic SSL via ACME.

🔐 Vault Integration

Configure external secret providers and manage encryption keys for production-grade security.

---

Validating your configuration

There is no nkapp config <env> validation subcommand — nkapp config is a writer (set / del / env / deploy / infra). To check that a config is valid and to see what it resolves to:

nkapp doctor            # parses and schema-validates nanokit.yml
nkapp plan -e <env>     # the fully resolved, environment-merged reconcile plan
nkapp env list -e <env> # the merged environment-variable view

Writing config implies executing commands

nanokit.yml expresses free-form shell in several places — services.*.start, services.*.command, services.*.hooks.*, provisioning.install, cron.*.command, and deploy.*.prepare (which runs on the remote host). Write access to this file, plus the ability to apply it, is equivalent to command execution on your machine and on every deploy target. Treat it with the same care as a deploy key.