Config files allow you to define a BYOC application using a single .toml file. Under the hood, Nuon will handle keeping your configuration in sync.

​
Create an app

Config files are used to sync the configuration for a single app. To create an app and an example config file:

nuon
nuon apps create --name=<app-name>

This will create an example config file named nuon.<app-name>.toml.

​
Sync an App

To sync an app, and it’s configuration run:

nuon
nuon apps sync

This will sync each configuration file in the current working directory.

To sync only a single file:

nuon
nuon apps sync -c <file>

Nuon uses terraform to keep your application config in sync. If you would like to migrate from a config file to terraform, you can run nuon apps export-terraform.

​
Export Terraform

You can export terraform from your application configuration using:

nuon
nuon apps export-terraform

​
Breaking up Config Files

As your config grows, keeping everything in a single file can become unmanagable. You can break out each section of an app config into it’s own file — and even re-use those sections with multiple apps — using the source and sources keywords.

For example, to break out each component into it’s own file, you would the following.

nuon.<your-app>.toml
[[components]]
source = "./storage.toml"

[[components]]
source = "./container_image.toml"
storage.toml
name = "storage"
type = "terraform_module"
terraform_version = "1.7.5"

[public_repo]
directory = "components/storage"
repo = "nuonco/demo"
branch = "main"
container_image.toml
name = "container_image"
type = "container_image"

[aws_ecr]
image_url = "ecr-repository"
tag = "latest"
region = "us-west-2"

When loading a component from a source, the components prefix is not needed for each field, like it is in the main config file.

You can also override fields from a source config file, by setting the values directly in your main toml file:

nuon.your-app.toml
[[components]]
source = "./storage.toml"
name = "storage"
storage.toml
type = "terraform_module"
terraform_version = "1.7.5"

​
Config Variables

You can define config variables to be used throughout your config, allowing you to set variables for common values.

To add a configuration variable, add the config_vars block to the top of your config file:

version = "v1"

[config_vars]
component_prefix = "app_"

You can then reference anywhere in your config:

[[components]]
name = "{{.component_prefix}}_storage"

Config variables do not currently work with reusable component files.

​
Validate

You can validate a config file using nuon apps validate:

nuon
nuon apps validate -c nuon.<your-app>.toml

The CLI will automatically generate Terraform code from your config and run terraform validate on it and print any errors.

​
Reference

​
Input Config

Define inputs for an app using the [input] block.

To configure a sensitive api_key and vpc_id input:

[inputs]
[[inputs.input]]
name = "vpc_id"
description = "vpc_id to install application into"
default = ""
sensitive = false
display_name = "VPC ID"

[[inputs.input]]
name = "api_key"
description = "API key"
default = ""
sensitive = true
display_name = "API Key"

Inputs are not required, unless you are using a sandbox that requires inputs (such as a byovpc one).

​
Runner Config

Define the runner for an app using a [runner] block.

To configure a runner for an ecs sandbox:

[runner]
runner_type = "aws-ecs"

[runner.env_vars]
runner-env-var = "runner-env-var"

Runners are a required configuration for all apps. In most cases, you do not need to customize them using environment variables.

​
Installer Config

Define an installer for an app using an [installer] block.

[installer]
name = "<your-app> Installer"
description = "Install <your-app> in your cloud."
homepage_url = "<your-homepage-url>"
documentation_url = "<your-docs-url>"
community_url = "<your-community-url>"
github_url = "<your-github-url>"
demo_url = "<your-demo-video-url>"
logo_url = "<your-logo-url>"
og_image_url = "<your-og-image-url>"
favicon_url = "<your-favicon-url>"

copyright_markdown = """
© 2024 <your-company>.
"""

footer_markdown = """
[Terms of Service](<your-terms-url>)
"""

post_install_markdown = """
# <your-app>

<your-app> is being deployed.
"""

apps = [
  "<your-app-id>",
  "<your-other-app-id>"
]

​
Sandbox Config

Define the sandbox for an app using a [sandbox] block.

To define an aws-ecs-byovpc sandbox:

[sandbox]
terraform_version = "1.7.5"
[sandbox.public_repo]
directory = "aws-ecs-byovpc"
repo = "nuonco/sandboxes"
branch = "main"

[sandbox.vars]
vpc_id = "{{.nuon.install.inputs.vpc_id}}"

​
Component Config

You can define components using a [components] block. Components must declare a type field and any relevant component-specific configuration.

Each component will have dependencies automatically defined based on the order in the config file. Learn more about depencencies here.

​
Terraform Module Component

To define a terraform module component use the terraform_module type.

To configure a terraform component using a connected repo:

[[components]]
name = "terraform"
type = "terraform_module"
terraform_version = "1.7.5"

[components.connected_repo]
directory = "infra"
repo = "org/repo"
branch = "main"

[components.env_vars]
AWS_REGION = "{{.nuon.install.sandbox.account.region}}"

[components.vars]
account_id = "{{.nuon.install.sandbox.account.id}}"

​
Helm Chart Component

To define a helm chart component use the helm_chart type.

To configure a helm chart in a connected repo:

[[components]]
name = "helm"
type = "helm_chart"
chart_name = "chart-name"

[components.connected_repo]
directory = "helm"
repo = "org/repo"
branch = "main"

[components.values]
"api.ingresses.public_domain" = "{{.nuon.components.infra.outputs.iam_role}}"

​
Docker Build Component

To define a docker build component use the docker_build type.

To configure a docker build component from a private repo:

[[components]]
name = "docker_build"
type = "docker_build"

dockerfile = "Dockerfile"

[components.connected_repo]
directory = "deployment"
repo = "powertoolsdev/mono"
branch = "main"

​
Container Image Component

To define a container image component use the container_image type.

To configure a public container image:

[[components]]
name = "container_image"
type = "container_image"

[components.public]
image_url = "kennethreitz/httpbin"
tag = "latest"

To configure a container image from an ECR repo:

[[components]]
name = "container_image_ecr"
type = "container_image"

[components.aws_ecr]
iam_role_arn = "iam_role_arn"
image_url = "ecr-url"
tag = "latest"
region = "us-west-2"

​
Job Component

To define a job component use the job type.

To configure a job using a docker image from another component:

[[components]]
name = "job"
type = "job"

image_url = "{{.nuon.components.e2e_docker_build.image.repository.uri}}"
tag   = "{{.nuon.components.e2e_docker_build.image.tag}}"
cmd   = ["printenv"]
args    = ["-a"]

[components.env_vars]
PUBLIC_DOMAIN = "{{.nuon.components.infra.outputs.iam_role}}"

To configure a job using a docker image from docker hub:

[[components]]
name = "job"
type = "job"

image_url = "bitnami/kubectl"
tag   = "latest"
cmd   = ["printenv"]
args    = ["-a"]

[components.env_vars]
PUBLIC_DOMAIN = "{{.nuon.components.infra.outputs.iam_role}}"