application.toml

A Nornor Heim application.toml file is used to define an application in Heim.

The application.toml is required for deploying an application to Heim.

---

contents

The application.toml file defines the attributes of an application. It names the application, sets a component target, defines application triggers, sets values to environment variables used by the application and defines scaling limits.

This example shows a simple application.toml file:

name = "example-application"
component_target = 'example-application:latest'

[[trigger]]
type = 'http'
path = '/test/api/*'
method = 'ALL'

[env]
variable1 = "Value for variable1"

[scaling]
region = ['localhost']
max-parallel = 4
max-memory = '512MiB'
max-cpu = 2
timeout = '1h'

[capabilities]
allowed-outgoing-url = ["https://upcloud.com/*", "https://dummyjson.com/*"]

An example application application.toml

name

This is a string identifier for your application.

A properly formatted, valid application name should only contain a combination of letters and digits, ie a-zA-Z0-9-_.

component_target

This refers to the target component for your application deployment.

Example value:

'example-application:latest'

trigger definitions

The application.toml can contain triggers definitions.

name	contents	required
type	trigger type in string format, example: http	yes
path	relative path in string format, example: /test/api/ and the path can also include wildcards *	yes
method	method value string – GET, POST, PATCH,HEAD, OPTIONS, TRACE, PUT, DELETE, CONNECT or ALL	yes

This is an example trigger definition declaration, for a trigger called “trigger.http”:

[[trigger]]
type = 'http'
path = '/test/api/*'
method = 'ALL'

env

The env section contains value assignments for environment variables.

Environment variables are value assignments for any environment variables expected by a component. Environment variables are declared in that component’s configuration file.

All non-optional environment variables for a component have to have a value assigned to them in this section.

This is an example of an env section with two environment variables:

[env]
VARIABLE_NAME = "VALUE1"
VARIABLE_NAME_TWO = "VALUE""

scaling definitions

These sections contain maximum allowed values an application may scale up to. The Heim tool will limit any resource usage beyond what is set here.

Scaling settings may be assigned to a specific region, or have their region setting declared as 'localhost'. There should be a main scaling setting, denoted as[scaling]. This section should contain a list of regions, and default scaling values used for all regions without a specific scaling setup. Additional, region-specific, scaling sections may be added, with headers in the format [scaling.${region}]. Any region-specific scaling section should be connected to a region in the main scaling section region list.

name	contents	required
region	list of regions in string format, example: ["eu-north-1", "eu-west-1"]	no
max-parallel	max-parallel deployments in positive integer format	no
max-memory	max allowed memory usage in string format, denoting number and unit, possible units being KiB, MiB or GiB	no
max-cpu	max allowed cpu cores used, in positive integer format	no
timeout	timeout for long-running processes in string format, denoting number and unit, example: 1h	no

This is an example of a main scaling section:

[scaling]
region = ['heim-localhost']
max-parallel = 4
max-memory = '1GiB'
max-cpu = 2
timeout = '1h'

This is an example of a region-specific scaling section:

[scaling.upcloud-se-1]
max-parallel = 2
max-memory = '500MiB'
max-cpu = 1
timeout = '2h'

Note that any region-specific scaling sections should refer to a region in the main scaling section.

capabilities definitions

The capabilities section contains allowed URLs that the application can communicate with.

All URLs can be declared fully or use the * wildcard to allow all paths for a specific domain.

This is an example of a capabilities section with two allowed URLs:

[capabilities]
allowed-outgoing-url = ["https://upcloud.com/*", "https://dummyjson.com/*"]

---

Summary

A application.toml file is used to declare an application that can be deployed to Heim.

section	format	required
name	identifier for your application, in string format	yes
component_target	reference to target component	yes
trigger definitions	sections containing trigger definitions	yes
env	section containing environment variable definitions	no
scaling definitions	sections containing scaling definitions	no
capabilities definitions	sections containing capabilities definitions	no