Golem Application Manifest Reference

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

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

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

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.

Optional map of HTTP API definitions by API name.

Required string version of the API.

Optional project reference for the API.

Optional array of HTTP routes.

Required HTTP method for the route, accepted values:

• CONNECT

  available since1.2.4
• DELETE

  available since1.2.4
• GET

  available since1.2.4
• HEAD

  available since1.2.4
• OPTIONS

  available since1.2.4
• PATCH

  available since1.2.4
• POST

  available since1.2.4
• PUT

  available since1.2.4
• TRACE

  available since1.2.4

Required HTTP path pattern for the route.

Optional ID of the required HTTP API security.

Required API binding.

*Optional binding type, accepted values:

• default(default value)

  available since1.2.4
• cors-preflight

  available since1.2.4
• file-server

  available since1.2.4
• file-handle

  available since1.2.4

Required name of the component to be used in the bindings.

Optional version of the component to be used in the bindings, default to the latest deployed one.

Optional Rib script for calculating the idempotency key.

Optional Rib script for calculating the invocation context.

Required Rib script for creating the response.

Optional map of HTTP API deployments by profile name.

Optional list of HTTP API deployments for the profile.

Required host for the deployment.

Optional subdomain for the deployment.

Required list of HTTP APIDefinitions for the deployment. Accepted formats: name or name@version.

Optional custom or customized profiles for the application by profile name.

Optional boolean which defaults to false. Only one profile can be marked as default.

Optional boolean which marks the profile as a cloud profile. Implicitly true for

Optional project reference for the profile.

Optional custom URL for golem services.

Optional custom URL for golem worker service.

Optional default format for the profile, accepted values:

• text(default value)

  available since1.2.4
• json

  available since1.2.4
• pretty-json

  available since1.3.0
• pretty

  available since1.3.0

  alias for pretty-json
• yaml

  available since1.2.4
• pretty-yaml

  available since1.3.0

Optional default build profile.

Optional boolean which defaults to false, when set to true it enables the auto-confirm (yes) flag by default.

Optional boolean which defaults to false, when set to true it enables redeploy-workers flag by default.

Optional boolean which defaults to false, when set to true it enables redeploy-agents flag by default.

Optional boolean which defaults to false, when set to true it enables redeploy-http-api flag by default.

Optional boolean which defaults to false, when set to true it enables redeploy-all flag by default.

Optional boolean which defaults to false, when set to true it enables reset flag by default.

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: # ...
    # ...

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.

Optional string enum of component types, accepted values:

• durable(default value)

  available since1.1.0
• ephemeral

  available since1.2.2
• library

  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

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

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.

Required target path of the file in the Initial File System. The path must be an absolute path.

Optional string enum which controls file permissions. Accepted values:

• read-only(default value)

  available since1.1.0
• read-write

  available since1.1.0

Optional list of component plugin installation entries,

Required name of the plugin.

Required version of the plugin.

Optional string map of plugin parameters.

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

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

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

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

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

Required external command that will be used as a build step for creating components.<component-name>.componentWasm.

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 ..

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.

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.

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

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.

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

Component specific customCommands.<command-name>[*].dir.

Component specific customCommands.<command-name>[*].rmdirs.

Component specific customCommands.<command-name>[*].mkdirs.

Component specific customCommands.<command-name>[*].mkdirs.

Component specific customCommands.<command-name>[*].sources.

Component specific customCommands.<command-name>[*].targets.

Component specific clean.

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 using profiles and have a profile named release
• will use the defaultProfile for components that using profiles, but do not have a profile named release

components:
  pack-ns:component-name:
    profiles:
      debug:
        build:
        - command: build-tool --debug out.wasm
      release:
        build:
        - command: build-tool --release out.wasm
    defaultProfile: release

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.

Profile specific components.<component-name>.componentType.

Profile specific components.<component-name>.files.

Profile specific components.<component-name>.files[*].sourcePath.

Profile specific components.<component-name>.files[*].targetPath.

Profile specific components.<component-name>.files[*].permissions.

Profile specific components.<component-name>.sourceWit.

Profile specific components.<component-name>.generatedWit.

Profile specific components.<component-name>.componentWasm.

Profile specific components.<component-name>.linkedWasm.

Profile specific components.<component-name>.build.

Profile specific components.<component-name>.build[*].command.

Profile specific components.<component-name>.build[*].dir.

Profile specific components.<component-name>.build[*].rmdirs.

Profile specific components.<component-name>.build[*].mkdirs.

Profile specific components.<component-name>.build[*].sources.

Profile specific components.<component-name>.build[*].targets.

Profile specific components.<component-name>.customCommands.

Profile specific components.<component-name>.customCommands.<command-name>[*].dir.

Profile specific components.<component-name>.customCommands.<command-name>[*].rmdirs.

Profile specific components.<component-name>.customCommands.<command-name>[*].mkdirs.

Profile specific components.<component-name>.customCommands.<command-name>[*].mkdirs.

Profile specific components.<component-name>.customCommands.<command-name>[*].sources.

Profile specific components.<component-name>.customCommands.<command-name>[*].targets.

Profile specific components.<component-name>.clean.

Optional map of list of component dependencies, which can be used for defining WASM RPC connections between components.

Required string enum, accepted values:

• wasm-rpc

  deprecated since1.3.0|available since1.1.0

  Dynamic 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.2

  Static WASM RPC linking.

  With this dependency type the linking happens locally, so it requires Rust tooling.

• wasm

  available since1.2.2

  Component linking.

Must be a defined component name. Required when dependencies.<component-name>[*].type is set to wasm-rpc or wasm-rpc-static.

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.

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.

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 targets
• the paths defined in common and component specific clean fields.

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

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 ..

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.

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.

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.

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.

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

Templated components.<component-name>.componentType.

Templated components.<component-name>.files.

Templated components.<component-name>.files[*].sourcePath.

Templated components.<component-name>.files[*].targetPath.

Templated components.<component-name>.files[*].permissions.

Templated components.<component-name>.sourceWit.

Templated components.<component-name>.generatedWit.

Templated components.<component-name>.componentWasm.

Templated components.<component-name>.linkedWasm.

Templated components.<component-name>.build.

Templated components.<component-name>.build[*].command.

Templated components.<component-name>.build[*].dir.

Templated components.<component-name>.build[*].rmdirs.

Templated components.<component-name>.build[*].mkdirs.

Templated components.<component-name>.build[*].sources.

Templated components.<component-name>.build[*].targets.

Templated components.<component-name>.customCommands.

Templated components.<component-name>.customCommands.<command-name>[*].dir.

Templated components.<component-name>.customCommands.<command-name>[*].rmdirs.

Templated components.<component-name>.customCommands.<command-name>[*].mkdirs.

Templated components.<component-name>.customCommands.<command-name>[*].mkdirs.

Templated components.<component-name>.customCommands.<command-name>[*].sources.

Templated components.<component-name>.customCommands.<command-name>[*].targets.

Templated components.<component-name>.clean.

Templated components.<component-name>.profiles.

Templated components.<component-name>.profiles.<profile-name>.

Templated and profile specific components.<component-name>.componentType.

Templated and profile specific components.<component-name>.files.

Templated and profile specific components.<component-name>.files[*].sourcePath.

Templated and profile specific components.<component-name>.files[*].targetPath.

Templated and profile specific components.<component-name>.files[*].permissions.

Templated and profile specific components.<component-name>.sourceWit.

Templated and profile specific components.<component-name>.generatedWit.

Templated and profile specific components.<component-name>.componentWasm.

Templated and profile specific components.<component-name>.linkedWasm.

Templated and profile specific components.<component-name>.build.

Templated and profile specific components.<component-name>.build[*].command.

Templated and profile specific components.<component-name>.build[*].dir.

Templated and profile specific components.<component-name>.build[*].rmdirs.

Templated and profile specific components.<component-name>.build[*].mkdirs.

Templated and profile specific components.<component-name>.build[*].sources.

Templated and profile specific components.<component-name>.build[*].targets.

Templated and profile specific components.<component-name>.customCommands.

Templated and profile specific components.<component-name>.customCommands.<command-name>.

Templated and profile specific components.<component-name>.customCommands.<command-name>[*].dir.

Templated and profile specific components.<component-name>.customCommands.<command-name>[*].rmdirs.

Templated and profile specific components.<component-name>.customCommands.<command-name>[*].mkdirs.

Templated and profile specific components.<component-name>.customCommands.<command-name>[*].mkdirs.

Templated and profile specific components.<component-name>.customCommands.<command-name>[*].sources.

Templated and profile specific components.<component-name>.customCommands.<command-name>[*].targets.

Templated and profile specific components.<component-name>.clean.

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