Managing App Templates

Create, configure, and manage app templates using the CLI and dashboard.

The CLI is the primary interface for managing app templates. The dashboard also provides limited app management. To see all available commands, run nuon apps --help.

Creating an App

Create a directory for your app config files in a GitHub repository, then create the app template:

mkdir your-app
cd your-app
nuon apps create --name=your-app

The directory can have any name. The app branch’s directory setting tells Nuon where to find it.

Pinning an App

Pin an app to set its ID as the default for all app commands, avoiding the need to pass -a each time:

nuon apps select
nuon apps current  # show the currently pinned app

Examples below assume you have run nuon apps select first.

Common Commands

nuon apps list              # list all apps
nuon apps get               # get info about the pinned app
nuon apps rename --name=new-name  # rename an app

Shipping Configuration

App config ships through an app branch. Add a branch file such as branches/main.toml that points at your repository, config directory, and git branch, then sync it once. Creating the branch also starts its first run:

nuon branches sync --file branches/main.toml

After that, pushing to the tracked git branch starts a run, which fetches your config and builds any component whose config changed (including related files such as a Helm values.yaml). To start a run without a push, or to rebuild components whose source changed while their config did not:

nuon branches trigger --branch-id main          # run the latest commit
nuon branches trigger --branch-id main --force  # rebuild every component

To check a config directory before you push, run nuon apps validate. It looks up the app by the directory’s name, so it works when the directory and the app share a name.

Viewing Configuration

nuon apps configs          # list all config versions
nuon apps runner-config    # print runner config
nuon apps sandbox-config   # print sandbox config
nuon apps input-config     # print input config

The output of runner-config, sandbox-config, and input-config is JSON. Pipe through jq or python -m json.tool for readability.

Metadata

Add metadata to your app via a metadata.toml file in the app root directory. This metadata is used in installers and the dashboard:

metadata.toml

display_name = "Your App"
description  = "A short description of your app."
readme       = "./README.md"

The readme field points to a Markdown file rendered in the dashboard for each install. See the Using READMEs guide for details.

Label colors

Give labels custom colors in the dashboard with a label_colors table in metadata.toml. Keys are label key names; values are hex color codes:

metadata.toml

[label_colors]
env      = "#FF5733"
region   = "#33FF57"
customer = "#3357FF"

The colors apply wherever those label keys appear in the dashboard: on apps, installs, and components. You can also set label colors directly in the dashboard; either source can be updated later, and the next run of your app branch will reconcile the values from your config.

Default labels

Apply labels to every install of an app with a default_labels table in metadata.toml:

metadata.toml

[default_labels]
service_tier   = "{{ .nuon.install.inputs.service_tier }}"

Values can use Nuon templating to render per install from install state, and re-render automatically as that state changes.

Default labels are owned by the app config. They locked on each install and cannot be updated manually or via install config. To change or remove a default label, you must edit default_labels in the app config. The change will propagate to each install when the new version of that app is released.