Golem Application Manifest Reference
JSON schema
For the application manifest format we also publish JSON schemas. The current version (1.1.1) is available here (opens in a new tab).
The JSON schema is intended to be used with editors and IDEs, to help with base validation and code completion.
Use the following YAML comments at the start of your golem.yaml
documents to enable schema support:
# $schema: https://schema.golem.cloud/app/golem/1.3.0/golem.schema.json
Note that on top of the above schema there are other checks performed by golem
, see the field reference below for details.
Loading of Application Manifest documents
The Golem CLI commands that use Application Manifest start by searching for golem.yaml
documents in the current and the parent directories. Once the top level manifest document is found, more manifests are searched based on the includes
fields.
After resolving relative paths in the documents they are merged, then component selection happens: this can be either explicit, by using --component-name
CLI flags, or implicit, in which case only components defined in the directory - including subdirectories - from where the Golem CLI was executed are used.
Application Manifest documents can also be explicitly passed to the CLI, using the --app
flag. Note that when using explicit documents the includes
field is not used, it is expected that all relevant documents are provided for the CLI.
Template variables and functions
The Application Manifest has some fields which are used as templates, these fields are marked as Templated in the field reference below. The templates are using minijinja (opens in a new tab), which is a minimal templating engine based on Jinja2 syntax.
Available template variables:
component_name
: contains the current component name in which the template is used
Available naming related string transforming functions:
to_snake_case
to_kebab_case
to_lower_camel_case
to_pascal_case
to_shouty_kebab_case
to_shouty_snake_case
to_snake_case
to_title_case
to_train_case
to_upper_camel_case
build: tool-name build {{ component_name | to_snake_case }}.wasm
Field reference
includes
Optional list of glob patterns that are used for adding search patterns for other Application Manifests when using auto discovery of them. The patterns are relative to the manifest document in which they are defined.
The default search pattern is **/golem.yaml
, which searches for golem.yaml
documents in every subdirectory
recursively. Templates and examples provided by Golem usually use more specific search patterns to make the lookups
more efficient.
The includes
fields can be defined in one manifest only, usually in the project root directory.
Defining it multiple times results in validation error.
includes:
- components-dir/*/golem.yaml
- custom-templates/golem-*.yaml
tempDir
Optional path that overrides the default path of the default temporary directory (golem-temp
) which is
used
for storing various intermediate artifacts.
The path is relative to the manifest document in which they are defined.
tempDir: target/golem-temp
witDeps
Optional list of paths of directories where WIT dependency packages can be stored. The paths are relative to the manifest document in which they are defined.
During component WIT generation these paths are checked for resolving missing dependencies. It is intended to be used for eliminating duplication of common dependencies and interfaces.
The witDeps
fields can be defined in one manifest only, usually in the project root directory.
Defining it multiple times results in validation error.
witDeps:
- wit-common/deps
httpApi
Optional object for defining HTTP APIs and HTTP API deployments. APIs and deployments can be defined in multiple manifests, and they are merged during deployment.
httpApi.definitions
Optional map of HTTP API definitions by API name.
httpApi.definitions.<http-api-name>.version
Required string version of the API.
httpApi.definitions.<http-api-name>.project
Optional project reference for the API.
httpApi.definitions.<http-api-name>.routes
Optional array of HTTP routes.
httpApi.definitions.<http-api-name>.routes[*].method
Required HTTP method for the route, accepted values:
CONNECT
available since1.2.4DELETE
available since1.2.4GET
available since1.2.4HEAD
available since1.2.4OPTIONS
available since1.2.4PATCH
available since1.2.4POST
available since1.2.4PUT
available since1.2.4TRACE
available since1.2.4
httpApi.definitions.<http-api-name>.routes[*].path
Required HTTP path pattern for the route.
httpApi.definitions.<http-api-name>.routes[*].security
Optional ID of the required HTTP API security.
httpApi.definitions.<http-api-name>.routes[*].binding
Required API binding.
httpApi.definitions.<http-api-name>.routes[*].type
*Optional binding type, accepted values:
default
(default value)available since1.2.4cors-preflight
available since1.2.4file-server
available since1.2.4file-handle
available since1.2.4
httpApi.definitions.<http-api-name>.routes[*].componentName
Required name of the component to be used in the bindings.
httpApi.definitions.<http-api-name>.routes[*].componentVersion
Optional version of the component to be used in the bindings, default to the latest deployed one.
httpApi.definitions.<http-api-name>.routes[*].idempotencyKey
Optional Rib script for calculating the idempotency key.
httpApi.definitions.<http-api-name>.routes[*].invocationContext
Optional Rib script for calculating the invocation context.
httpApi.definitions.<http-api-name>.routes[*].response
Required Rib script for creating the response.
httpApi.deployments
Optional map of HTTP API deployments by profile name.
httpApi.deployments.<profile-name>
Optional list of HTTP API deployments for the profile.
httpApi.deployments.<profile-name>[*].host
Required host for the deployment.
httpApi.deployments.<profile-name>[*].subdomain
Optional subdomain for the deployment.
httpApi.deployments.<profile-name>[*].definitions
Required list of HTTP APIDefinitions for the deployment.
Accepted formats: name
or name@version
.
profiles
Optional custom or customized profiles for the application by profile name.
profiles.<profile-name>.default
Optional boolean which defaults to false. Only one profile can be marked as default.
profiles.<profile-name>.cloud
Optional boolean which marks the profile as a cloud profile. Implicitly true for
profiles.<profile-name>.project
Optional project reference for the profile.
profiles.<profile-name>.url
Optional custom URL for golem services.
profiles.<profile-name>.workerUrl
Optional custom URL for golem worker service.
profiles.<profile-name>.format
Optional default format for the profile, accepted values:
text
(default value)available since1.2.4json
available since1.2.4pretty-json
available since1.3.0pretty
available since1.3.0alias forpretty-json
yaml
available since1.2.4pretty-yaml
available since1.3.0
profiles.<profile-name>.buildProfile
Optional default build profile.
profiles.<profile-name>.autoConfirm
Optional boolean which defaults to false, when set to true it enables the auto-confirm (yes) flag by default.
profiles.<profile-name>.redeployWorkers
Optional boolean which defaults to false, when set to true it enables redeploy-workers flag by default.
profiles.<profile-name>.redeployAgents
Optional boolean which defaults to false, when set to true it enables redeploy-agents flag by default.
profiles.<profile-name>.redeployHttpApi
Optional boolean which defaults to false, when set to true it enables redeploy-http-api flag by default.
profiles.<profile-name>.redeployAll
Optional boolean which defaults to false, when set to true it enables redeploy-all flag by default.
profiles.<profile-name>.reset
Optional boolean which defaults to false, when set to true it enables reset flag by default.
components
Optional map of Golem components indexed by component-name
-s used for defining components.
The components
field can be defined in multiple manifest documents, but the used component-name
-s must be
unique across all the used manifest documents. Using the same component-name
more then once results in
validation error.
components:
pack-ns:component-name:
sourceWit: # ...
# ...
pack:comp-b:
sourceWit: # ...
# ...
components.<component-name>.template
Optional template name which will be used for creating the component fields.
The template name must be one of that are defined in templates
.
See templates
and Template variable and functions
for defining templates.
components.<component-name>.componentType
Optional string enum of component types, accepted values:
durable
(default value)available since1.1.0ephemeral
available since1.2.2library
available since1.2.2
See Ephemeral vs Durable Workers for more information about component types.
components:
pack-ns:component-name:
# ...
componentType: durable
pack-ns:component-name:
# ...
componentType: ephemeral
components.<component-name>.files
Optional list of files entries, which can be used for defining the Initial File System for the component.
components:
pack-ns:component-name:
# ...
files:
- sourcePath: ./files/foo.txt
targetPath: /files/foo.txt
permissions: read-only
- sourcePath: ./files/bar.txt
targetPath: /files/bar.txt
permissions: read-write
components.<component-name>.files[*].sourcePath
Required source path of the file to be added to the Initial File System. The path can be a file path relative to the manifest document or an URL.
components.<component-name>.files[*].targetPath
Required target path of the file in the Initial File System. The path must be an absolute path.
components.<component-name>.files[*].permissions
Optional string enum which controls file permissions. Accepted values:
read-only
(default value)available since1.1.0read-write
available since1.1.0
components.<component-name>.plugins
Optional list of component plugin installation entries,
components.<component-name>.plugins[*].name
Required name of the plugin.
components.<component-name>.plugins[*].version
Required version of the plugin.
components.<component-name>.plugins[*].parameters
Optional string map of plugin parameters.
components.<component-name>.sourceWit
Required directory path for the user defined component WIT directory.
The path is relative to the manifest document in which the field is defined.
The WIT directory can omit the deps
folder if the required dependencies are
available in some of the folders defined in witDeps
.
components:
pack-ns:component-name:
# ...
sourceWit: wit
components.<component-name>.generatedWit
Required directory path for the generated WIT directory created by the golem tooling, which handles exported interface extraction and includes resolved package and client dependencies.
This directory is intended to be used as source for binding generation.
The path is relative to the manifest document in which the field is defined.
This folder is usually added to .gitignore
, as it is generated as part of build.
components:
pack-ns:component-name:
# ...
generatedWit: wit-generated
components.<component-name>.componentWasm
Required file path which should point to the built component WASM file before linking.
The path is relative to the manifest document in which the field is defined.
This file is usually added to .gitignore
, as it is created as part of build.
components:
pack-ns:component-name:
# ...
componentWasm: build/component.wasm
components.<component-name>.linkedWasm
Optional file path which should point to the built component WASM file after linking.
Defaults to golem-temp/linked-wasm/component-name.wasm
, see tempDir
.
The path is relative to the manifest document in which the field is defined.
This file is usually added to .gitignore
, as it is created as part of build.
components:
pack-ns:component-name:
# ...
linkedWasm: golem-temp/component/component.wasm
components.<component-name>.build
Optional list of build commands that creates components.<component-name>.componentWasm
.
components:
pack-ns:component-name:
build:
- command: bindgen-tool wit-generated
- command: build-tool wit-generated component.wasm
components.<component-name>.build[*].command
Required external command that will be used as a build step for creating
components.<component-name>.componentWasm
.
components.<component-name>.build[*].dir
Optional directory path which will be used as working directory when executing
components.<component-name>.build[*].command
.
The path is relative to the manifest document, and defaults to .
.
components.<component-name>.build[*].rmdirs
Optional list of directory paths which will be deleted before executing the command.
The path is relative to components.<component-name>.build[*].dir
.
The rmdirs
field is useful when a binding generator does not automatically clean stale bindings.
Directories are not removed if the command is skipped because of up-to-date checks, see
components.<component-name>.build[*].sources
and
components.<component-name>.build[*].targets
.
Directories are removed before executing components.<component-name>.build[*].mkdirs
.
components.<component-name>.build[*].mkdirs
Optional list of directory paths which will be created before executing the command if they do not exists.
The path is relative to components.<component-name>.build[*].dir
.
The mkdirs
field is useful when a build of binding generator tool does not automatically create
required nested folders.
Directories are not created if the command is skipped because of up-to-date checks, see
components.<component-name>.build[*].sources
and
components.<component-name>.build[*].targets
.
Directories are created after executing components.<component-name>.build[*].rmdirs
.
components.<component-name>.build[*].sources
Optional list of paths and globs which are used as sources for performing up-to-date checks.
If defined then components.<component-name>.build[*].targets
also have to be used.
The up-to-date check
- skips executing
components.<component-name>.build[*].command
- if all matching files defined by
components.<component-name>.build[*].targets
- are newer then the matched files defined by
sources
.
components:
pack-ns:component-name:
# ...
build:
- command: build-tool src-dir out.wasm
sources:
- src-dir/*
targets:
- out.wasm
components.<component-name>.build[*].targets
Optional list of paths and globs which are used as targets for performing up-to-date checks.
If defined then components.<component-name>.build[*].sources
also have to be used.
See components.<component-name>.build[*].sources
for up-to-date check details.
components.<component-name>.customCommands
Optional map of component specific external commands, which are useful for defining e.g. one time installation or update related commands for the component.
The commands can be executed using:
golem app command-name
Multiple components can use the same command-name
, the above command will execute all matching
commands in this case, both component specific and project ones.
For defining project level custom commands see customCommands
.
The following command names cannot be used, as they are used by golem app
itself:
build
clean
components:
pack-ns:component-name:
# ...
customCommands:
npm-install:
- command: npm install
components.<component-name>.customCommands.<command-name>[*].dir
components.<component-name>.customCommands.<command-name>[*].rmdirs
components.<component-name>.customCommands.<command-name>[*].mkdirs
components.<component-name>.customCommands.<command-name>[*].mkdirs
components.<component-name>.customCommands.<command-name>[*].sources
components.<component-name>.customCommands.<command-name>[*].targets
components.<component-name>.clean
components.<component-name>.profiles
Optional map of profiles, which can be used to provide multiple build profiles for a component, typically used for debug and release configurations.
A profile contains the same fields as a component, expect for defaultProfile
and profile
itself.
When profiles
are defined for a component:
components.<component-name>.defaultProfile
must be defined,- non-profile component fields should not be used on the component, apart from
defaultProfile
.
When building, by default golem
will use defaultProfile
, unless a specific profile is requested and_
the component has a matching profile. E.g. the following command:
golem app --build-profile release build
- will build components that have no profiles by using the non-profile component fields
- will use the
release
profile for components that are usingprofiles
and have a profile namedrelease
- will use the
defaultProfile
for components that usingprofiles
, but do not have a profile namedrelease
components:
pack-ns:component-name:
profiles:
debug:
build:
- command: build-tool --debug out.wasm
release:
build:
- command: build-tool --release out.wasm
defaultProfile: release
components.<component-name>.defaultProfile
Optional profile name that defines which profile should be used.
It must be defined when using components.<component-name>.profiles
, and must be one of the
profile names defined there.
components.<component-name>.profiles.<profile-name>.componentType
components.<component-name>.profiles.<profile-name>.files
components.<component-name>.profiles.<profile-name>.files[*].sourcePath
components.<component-name>.profiles.<profile-name>.files[*].targetPath
components.<component-name>.profiles.<profile-name>.files[*].permissions
components.<component-name>.profiles.<profile-name>.sourceWit
components.<component-name>.profiles.<profile-name>.generatedWit
components.<component-name>.profiles.<profile-name>.componentWasm
components.<component-name>.profiles.<profile-name>.linkedWasm
components.<component-name>.profiles.<profile-name>.build
components.<component-name>.profiles.<profile-name>.build[*].command
components.<component-name>.profiles.<profile-name>.build[*].dir
components.<component-name>.profiles.<profile-name>.build[*].rmdirs
components.<component-name>.profiles.<profile-name>.build[*].mkdirs
components.<component-name>.profiles.<profile-name>.build[*].sources
components.<component-name>.profiles.<profile-name>.build[*].targets
components.<component-name>.profiles.<profile-name>.customCommands
components.<component-name>.profiles.<profile-name>.customCommands.<command-name>[*].dir
Profile specific components.<component-name>.customCommands.<command-name>[*].dir
.
components.<component-name>.profiles.<profile-name>.customCommands.<command-name>[*].rmdirs
Profile specific components.<component-name>.customCommands.<command-name>[*].rmdirs
.
components.<component-name>.profiles.<profile-name>.customCommands.<command-name>[*].mkdirs
Profile specific components.<component-name>.customCommands.<command-name>[*].mkdirs
.
components.<component-name>.profiles.<profile-name>.customCommands.<command-name>[*].mkdirs
Profile specific components.<component-name>.customCommands.<command-name>[*].mkdirs
.
components.<component-name>.profiles.<profile-name>.customCommands.<command-name>[*].sources
Profile specific components.<component-name>.customCommands.<command-name>[*].sources
.
components.<component-name>.profiles.<profile-name>.customCommands.<command-name>[*].targets
Profile specific components.<component-name>.customCommands.<command-name>[*].targets
.
components.<component-name>.profiles.<profile-name>.clean
dependencies
Optional map of list of component dependencies, which can be used for defining WASM RPC connections between components.
dependencies.<component-name>[*].type
Required string enum, accepted values:
wasm-rpc
deprecated since1.3.0|available since1.1.0Dynamic WASM RPC linking.
With this dependency type the linking happens on servers side, so there is no need for generating and creating WASM RPC clients.
wasm-rpc-static
deprecated since1.3.0|available since1.2.2Static WASM RPC linking.
With this dependency type the linking happens locally, so it requires Rust tooling.
wasm
available since1.2.2Component linking.
dependencies.<component-name>[*].target
Must be a defined component name. Required when dependencies.<component-name>[*].type
is
set to wasm-rpc
or wasm-rpc-static
.
dependencies.<component-name>[*].path
Target component WASM path to be used as dependency for linking.
When dependencies.<component-name>[*].type
is set to wasm
then this or
dependencies.<component-name>[*].url
ir required.
dependencies.<component-name>[*].url
Target component WASM path to be used as dependency for linking.
When dependencies.<component-name>[*].type
is set to wasm
then this or
dependencies.<component-name>[*].path
ir required.
clean
Optional list of paths which are added as targets to the golem app clean
command.
The paths are relative to the manifest document.
The clean
command deletes the following paths:
-
tempDir
-
components.<component-name>.generatedWit
-
components.<component-name>.linkedWasm
- build and custom command
target
s - the paths defined in common and component specific
clean
fields.
Related fields:
customCommands
Optional map of custom external commands, which are useful for defining e.g. one time installation or update related project commands.
The commands can be executed using:
golem app command-name
Components specific custom commands can use the same command-name
, the above command will execute all matching
commands in this case, both component specific and project ones.
For defining component specific custom commands see components.<component-name>.customCommands
.
The following command names cannot be used, as they are used by golem app
itself:
build
clean
customCommands:
npm-install:
- command: npm install
customCommands.<command-name>[*].dir
Optional directory path which will be used as working directory when executing
customCommands.<command-name>[*].command
.
The path is relative to the manifest document, and defaults to .
.
customCommands.<command-name>[*].rmdirs
Optional list of directory paths which will be deleted before executing the command.
The path is relative to customCommands.<command-name>[*].dir
.
The rmdirs
field is useful when a binding generator does not automatically clean stale bindings.
Directories are not removed if the command is skipped because of up-to-date checks, see
customCommands.<command-name>[*].sources
and
customCommands.<command-name>[*].targets
.
Directories are removed before executing customCommands.<command-name>[*].mkdirs
.
customCommands.<command-name>[*].mkdirs
Optional list of directory paths which will be created before executing the command if they do not exists.
The path is relative to customCommands.<command-name>[*].dir
.
The mkdirs
field is useful when a build of binding generator tool does not automatically create
required nested folders.
Directories are not created if the command is skipped because of up-to-date checks, see
customCommands.<command-name>[*].sources
and
customCommands.<command-name>[*].targets
.
Directories are created after executing customCommands.<command-name>[*].rmdirs
.
customCommands.<command-name>[*].sources
Optional list of paths and globs which are used as sources for performing up-to-date checks.
If defined then customCommands.<command-name>[*].targets
also have to be used.
The up-to-date check
- skips executing
customCommands.<command-name>[*].command
- if all matching files defined by
customCommands.<command-name>[*].targets
- are newer then the matched files defined by
sources
.
customCommands.<command-name>[*].targets
Optional list of paths and globs which are used as targets for performing up-to-date checks.
If defined then customCommands.<command-name>[*].sources
also have to be used.
See customCommands.<command-name>[*].sources
for up-to-date check details.
templates
Optional map of named templates, which can be used in components.<component-name>.template
.
Templates help in extracting common build patterns and reuse them for multiple components.
The templates
field can be defined in multiple application manifest documents, but the template names must be
unique.
See Template variable and functions for more information about templating.
templates:
my-template:
sourceWit: wit
componentWasm: build/{{component_name | to_snake_case}}
# ...
my-template-with-profiles:
profiles:
debug:
# ...
release:
# ...
components:
pack-ns:component-a:
template: my-template
pack-ns:component-b:
template: my-template
sourceWit: custom-wit # override
pack-ns:component-c:
template: my-template-with-profiles
profiles:
debug:
sourceWit: custom-wit # override
templates.<template-name>.componentType
templates.<template-name>.files
templates.<template-name>.files[*].sourcePath
templates.<template-name>.files[*].targetPath
templates.<template-name>.files[*].permissions
templates.<template-name>.sourceWit
templates.<template-name>.generatedWit
templates.<template-name>.componentWasm
templates.<template-name>.linkedWasm
templates.<template-name>.build
templates.<template-name>.build[*].command
templates.<template-name>.build[*].dir
templates.<template-name>.build[*].rmdirs
templates.<template-name>.build[*].mkdirs
templates.<template-name>.build[*].sources
templates.<template-name>.build[*].targets
templates.<template-name>.customCommands
templates.<template-name>.customCommands.<command-name>[*].dir
templates.<template-name>.customCommands.<command-name>[*].rmdirs
templates.<template-name>.customCommands.<command-name>[*].mkdirs
templates.<template-name>.customCommands.<command-name>[*].mkdirs
templates.<template-name>.customCommands.<command-name>[*].sources
templates.<template-name>.customCommands.<command-name>[*].targets
templates.<template-name>.clean
templates.<template-name>.profiles
templates.<template-name>.profiles.<profile-name>
templates.<template-name>.profiles.<profile-name>.componentType
templates.<template-name>.profiles.<profile-name>.files
templates.<template-name>.profiles.<profile-name>.files[*].sourcePath
templates.<template-name>.profiles.<profile-name>.files[*].targetPath
templates.<template-name>.profiles.<profile-name>.files[*].permissions
Templated and profile specific components.<component-name>.files[*].permissions
.
templates.<template-name>.profiles.<profile-name>.sourceWit
templates.<template-name>.profiles.<profile-name>.generatedWit
templates.<template-name>.profiles.<profile-name>.componentWasm
templates.<template-name>.profiles.<profile-name>.linkedWasm
templates.<template-name>.profiles.<profile-name>.build
templates.<template-name>.profiles.<profile-name>.build[*].command
templates.<template-name>.profiles.<profile-name>.build[*].dir
templates.<template-name>.profiles.<profile-name>.build[*].rmdirs
templates.<template-name>.profiles.<profile-name>.build[*].mkdirs
templates.<template-name>.profiles.<profile-name>.build[*].sources
templates.<template-name>.profiles.<profile-name>.build[*].targets
templates.<template-name>.profiles.<profile-name>.customCommands
templates.<template-name>.profiles.<profile-name>.customCommands.<command-name>
Templated and profile specific components.<component-name>.customCommands.<command-name>
.
templates.<template-name>.profiles.<profile-name>.customCommands.<command-name>[*].dir
Templated and profile specific components.<component-name>.customCommands.<command-name>[*].dir
.
templates.<template-name>.profiles.<profile-name>.customCommands.<command-name>[*].rmdirs
Templated and profile specific components.<component-name>.customCommands.<command-name>[*].rmdirs
.
templates.<template-name>.profiles.<profile-name>.customCommands.<command-name>[*].mkdirs
Templated and profile specific components.<component-name>.customCommands.<command-name>[*].mkdirs
.
templates.<template-name>.profiles.<profile-name>.customCommands.<command-name>[*].mkdirs
Templated and profile specific components.<component-name>.customCommands.<command-name>[*].mkdirs
.
templates.<template-name>.profiles.<profile-name>.customCommands.<command-name>[*].sources
Templated and profile specific components.<component-name>.customCommands.<command-name>[*].sources
.
templates.<template-name>.profiles.<profile-name>.customCommands.<command-name>[*].targets
Templated and profile specific components.<component-name>.customCommands.<command-name>[*].targets
.
templates.<template-name>.profiles.<profile-name>.clean
templates.<template-name>.defaultProfile
String which selects the default profile for the template. Required if profiles are used. Must be one
of the defined profile names in templates.<template-name>.profiles
.
templates:
rust:
profiles:
debug:
# ...
release:
# ...
defaultProfile: debug
Fields and changes by releases
library
tocomponents.<component-name>[*].componentType
resetWorkers
to resetAgents