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 (AWS, 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 database engines like PostgreSQL, MySQL, 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, postup, and onfailure.

🛡️ 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.

[!TIP] Pro Tip: You can always validate your resolved configuration for any environment using the command: nkapp config -e <env>