App Initialization

The nuon apps init command helps you quickly scaffold configuration files for your Nuon application. It generates the necessary TOML configuration files with proper structure and defaults, making it easy to get started with Nuon.

Basic Usage

To initialize a new app configuration in the default directory (./app-config):

nuon apps init

This generates a complete app configuration structure with all core configuration files:

inputs.toml - Define customer-facing configuration options
sandbox.toml - Configure the infrastructure sandbox
stack.toml - Define the stack
runner.toml - Configure the deployment runner
secrets.toml - Manage secrets configuration
break_glass.toml - Configure emergency access policies
policies.toml - Define organizational policies
components/ - Directory for component configurations
actions/ - Directory for action workflows

Interactive Mode

For a guided setup experience, use interactive mode:

nuon apps init --interactive
# or
nuon apps init -i

Interactive mode walks you through:

Template Selection - Choose a prebuilt template or start from scratch
Component Configuration - Select which sample components to include
Generator Options - Configure comment and default value preferences

This is especially helpful when you’re new to Nuon or want to explore available options.

Using Prebuilt Templates

Nuon provides production-ready templates for common deployment scenarios. Use the --prebuild-template flag to bootstrap your configuration quickly:

AWS EKS Template

nuon apps init --prebuild-template aws-eks

This generates a complete configuration optimized for deploying containerized applications to AWS Elastic Kubernetes Service (EKS). Additional templates coming soon…

Configuration Options

Path Configuration

Specify a custom output directory:

nuon apps init --path ./my-app-config

Include Comments

Add inline comments explaining each configuration field:

nuon apps init --enable-comments

This is helpful for learning and understanding configuration options.

Include Default Values

Explicitly set all fields to their default values:

nuon apps init --enable-defaults

By default, only required fields are included. This flag shows all available options.

Skip Non-Required Fields

Generate a minimal configuration with only required fields:

nuon apps init --skip-non-required

This creates a cleaner starting point when you know you’ll customize extensively.

Overwrite Existing Files

Force overwrite of existing configuration files:

nuon apps init --overwrite

Be careful with --overwrite as it will replace existing files without prompting. Always commit your changes to version control before using this flag.

Initializing Individual Configurations

Instead of generating the entire configuration structure, you can initialize specific configuration files using subcommands.

Sandbox Configuration

Generate only the sandbox configuration:

nuon apps init sandbox \
  --terraform-version 1.11.3 \
  --public-repo nuonco/aws-eks-sandbox \
  --public-repo-dir terraform \
  --public-repo-branch main \
  --var region=us-west-2 \
  --env-var LOG_LEVEL=info

Key flags:

--terraform-version - Terraform version to use
--public-repo - Public GitHub repository (e.g., owner/repo)
--connected-repo - Connected private repository
--drift-schedule - Cron expression for drift detection
--var - Terraform variable (can be specified multiple times)
--env-var - Environment variable (can be specified multiple times)

Stack Configuration

Generate the stack configuration.

nuon apps init stack \
  --name my-app-stack \
  --description "Production EKS cluster" \
  --type aws-cloudformation \
  --vpc-template-url https://s3.amazonaws.com/templates/vpc.yaml \
  --runner-template-url https://s3.amazonaws.com/templates/runner.yaml

Required flags:

--name - Name of the stack
--description - Description of the stack

Supported --type values: aws-cloudformation, azure-bicep (Azure), gcp-terraform (Google Cloud).

Runner Configuration

Generate the runner configuration:

nuon apps init runner \
  --runner-type kubernetes \
  --helm-driver configmap \
  --env-var NUON_LOG_LEVEL=debug

Required flags:

--runner-type - Type of runner: kubernetes, docker, or vm

Component Configurations

Generate component configuration files for different component types.

Terraform Module Component

nuon apps init component terraform-module \
  --name database \
  --var-name db \
  --terraform-version 1.11.3 \
  --connected-repo my-org/my-repo \
  --connected-repo-dir terraform/database \
  --var environment=production \
  --dependency vpc

Helm Chart Component

nuon apps init component helm-chart \
  --name postgresql \
  --chart-name postgresql \
  --helm-repo-url https://charts.bitnami.com/bitnami \
  --helm-chart postgresql \
  --helm-version 12.0.0 \
  --namespace databases \
  --value persistence.enabled=true \
  --dependency vpc

Kubernetes Manifest Component

nuon apps init component kubernetes-manifest \
  --name app-deployment \
  --namespace default \
  --manifest "apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3"

Action Configuration

Generate an action workflow configuration:

nuon apps init action \
  --name backup \
  --trigger-type cron \
  --cron-schedule "0 2 * * *" \
  --step-name run-backup \
  --step-command "./backup.sh" \
  --connected-repo my-org/my-repo \
  --connected-repo-dir scripts \
  --env-var BACKUP_BUCKET=s3://backups

Common trigger types:

manual - Triggered manually from dashboard or CLI
cron - Scheduled using cron expression
post-provision-sandbox - Runs after initial sandbox provisioning and before component deployment
post-provision - Runs after installation provisioning
post-deploy-component - Runs after deployment of the component specified by component_name
post-deploy-all-components - Runs after an all-components deployment

Common Workflows

Starting a New Application

Initialize with template:

nuon apps init --interactive --path ./my-app

Review and edit generated files:
cd my-app cat app.toml

Customize components:

nuon apps init component helm-chart \
  --name api \
  --chart-name my-api-chart \
  --connected-repo my-org/charts \
  --connected-repo-dir api

Sync to Nuon:
nuon apps sync

Adding to an Existing Application

If you already have some configuration files and want to add more:

# Add a new component without overwriting existing files
nuon apps init component terraform-module \
  --name new-service \
  --path ./app-config

Regenerating Configuration

If you need to regenerate with different options:

# Backup first
cp -r app-config app-config.backup

# Regenerate with comments and defaults
nuon apps init \
  --path ./app-config \
  --enable-comments \
  --enable-defaults \
  --overwrite

Configuration File Structure

After running nuon apps init, your directory will have this structure:

app-config/
├── inputs.toml           # Customer-facing configuration
├── sandbox.toml          # Infrastructure sandbox
├── stack.toml            # Infrastructure stack definition
├── runner.toml           # Runner configuration
├── secrets.toml          # Secrets management
├── break_glass.toml      # Emergency access
├── policies.toml         # Organizational policies
├── components/           # Component definitions
│   ├── component1.toml
│   └── component2.toml
├── permissions /           # Permission definitions
│   ├── provision.toml
│   └── deprovision.toml
│   └── maintenance.toml
└── actions/              # Action workflows
    ├── action1.toml
    └── action2.toml

Next Steps

After initializing your app configuration:

Review Generated Files - Open each TOML file and customize values for your application
Add Components - Use nuon apps init component to add application-specific components
Configure Actions - Set up automated workflows with nuon apps init action
Sync to Nuon - Run nuon apps sync to create or update your app in Nuon
Test Locally - Validate your configuration before deploying

The nuon apps init command is a local operation and does not require authentication. It only generates configuration files on your local machine. Use nuon apps sync to push your configuration to the Nuon platform.

Tips and Best Practices

Version Control

Always commit generated configuration files to version control:

git add app-config/
git commit -m "Initialize Nuon app configuration"

Iterative Development

Start minimal and add complexity as needed:

# Start with minimal config
nuon apps init --skip-non-required

# Add components incrementally
nuon apps init component helm-chart --name api
nuon apps init component terraform-module --name database

Use Comments for Learning

When learning Nuon, generate files with comments:

nuon apps init --enable-comments --enable-defaults

This creates well-documented configuration files that explain each option.

Template Customization

After using a prebuilt template, customize it for your needs:

# Start with template
nuon apps init --prebuild-template aws-eks

# Customize sandbox
nuon apps init sandbox --overwrite \
  --var region=eu-west-1 \
  --var instance_type=t3.large

Connect Your App

Install with a Customer

Day 2 Operations

Integrations

Advanced

Basic Usage

Interactive Mode

Using Prebuilt Templates

AWS EKS Template

Configuration Options

Path Configuration

Include Comments

Include Default Values

Skip Non-Required Fields

Overwrite Existing Files

Initializing Individual Configurations

Sandbox Configuration

Stack Configuration

Runner Configuration

Component Configurations

Terraform Module Component

Helm Chart Component

Kubernetes Manifest Component

Action Configuration

Common Workflows

Starting a New Application

Adding to an Existing Application

Regenerating Configuration

Configuration File Structure

Next Steps

Tips and Best Practices

Version Control

Iterative Development

Use Comments for Learning

Template Customization

​Basic Usage

​Interactive Mode

​Using Prebuilt Templates

​AWS EKS Template

​Configuration Options

​Path Configuration

​Include Comments

​Include Default Values

​Skip Non-Required Fields

​Overwrite Existing Files

​Initializing Individual Configurations

​Sandbox Configuration

​Stack Configuration

​Runner Configuration

​Component Configurations

​Terraform Module Component

​Helm Chart Component

​Kubernetes Manifest Component

​Action Configuration

​Common Workflows

​Starting a New Application

​Adding to an Existing Application

​Regenerating Configuration

​Configuration File Structure

​Next Steps

​Tips and Best Practices

​Version Control

​Iterative Development

​Use Comments for Learning

​Template Customization

Basic Usage

Interactive Mode

Using Prebuilt Templates

AWS EKS Template

Configuration Options

Path Configuration

Include Comments

Include Default Values

Skip Non-Required Fields

Overwrite Existing Files

Initializing Individual Configurations

Sandbox Configuration

Stack Configuration

Runner Configuration

Component Configurations

Terraform Module Component

Helm Chart Component

Kubernetes Manifest Component

Action Configuration

Common Workflows

Starting a New Application

Adding to an Existing Application

Regenerating Configuration

Configuration File Structure

Next Steps

Tips and Best Practices

Version Control

Iterative Development

Use Comments for Learning

Template Customization