Welcome to the new Golem Cloud Docs! 👋
Documentation
Application Manifest

Golem Application Manifest

The Golem Application Manifest document format is used by golem-cli, usually stored in files named golem.yaml, which can help working with components. Currently, the Application Manifest covers:

  • defining components and their metadata, including:
    • component type
    • location of user defined and generated WIT folders
    • location of built and composed WASM binaries
    • build commands
    • Initial File System
  • defining component dependencies for using Worker to Worker communication
  • building components
  • deploying components

The Application Manifest uses YAML format, see the reference for more information on the schema and for the field reference.

Application Manifest Quickstart

Application manifest documents can be explicitly passed as golem-cli arguments, but the recommended way to use them is with auto discovery mode: when golem-cli is called with an application manifest compatible command it keeps searching for golem.yaml documents in current working directory and parent directories. Once it found the top level golem.yaml document, more documents are searched using the includes field.

Once all manifest documents are found, the paths in them are resolved based on their directory, and then the documents are merged. For the field specific merge rules see the field reference.

Using composable templates

Golem example projects can be created with golem-cli new command, these are stand-alone project, usually containing one component. To help with setting up multi-component projects, the CLI now includes a new command, new-app-component, which can be used in empty or existing projects to add new components. E.g.: let's add a new cpp and ts component in a new and empty directory:

mkdir app-demo
cd app-demo
golem-cli new-app-component --language cpp app:component-a
golem-cli new-app-component --language ts app:component-b

When using the new-app-component command, it will create:

  • common directory for the given language (common-cpp and common-ts):
    • this directory contains the languages specific Application Manifest Template, which defines how to build the components
    • can be used for shared subprojects
    • might contain other shared configurations
  • directory for components for the given language (components-cpp and components-ts)
  • directory called common-wit-deps for common WIT dependencies, and populates it with WASI and Golem packages
  • depending on the language it might add common-adapters.

Now that we added our components, let's use the app command list our project metadata:

$ golem-cli app
 
Build components with application manifests
 
Usage: golem-cli app [OPTIONS] [COMMAND]
 
Commands:
  build  Run component build steps
  clean  Clean outputs
  help   Print this message or the help of the given subcommand(s)
 
Options:
  -a, --app <APP>
Application manifest to be used, can be defined multiple times
  -c, --component-name <COMPONENT_NAME>
Selects a component, can be defined multiple times
  -b, --build-profile <BUILD_PROFILE>
Selects a build profile
  -o, --offline
When set to true will use offline mode where applicable (e.g. stub cargo builds), defaults to false
  -h, --help
Print help
 
Components:
  app:component-a
    Selected:     yes
    Source:       /Users/<...>/app-demo/components-cpp/app-component-a/golem.yaml
    Template:     cpp
    Profiles:     debug, release
  app:component-b
    Selected:     yes
    Source:       /Users/<...>/app-demo/components-ts/app-component-b/golem.yaml
    Template:     ts
 
Custom commands:
  npm-install

Because the ts components use npm, we have to use npm install before building the components. We can also see that this has a wrapper custom command in the manifest called npm-install. Let's use that, then build our components:

$ golem-cli app npm-install
<..>
$ golem-cli app build
Collecting sources
  Found sources: /Users/<...>/app-demo/common-cpp/golem.yaml, /Users/<...>/app-demo/common-ts/golem.yaml, /Users/<...>/app-demo/components-cpp/app-component-a/golem.yaml, /Users/<...>/app-demo/components-ts/app-component-b/golem.yaml, /Users/<...>/app-demo/golem.yaml
Collecting components
  Found components: app:component-a, app:component-b
Resolving application wit directories
  Resolving component wit dirs for app:component-a (/Users/<...>/app-demo/components-cpp/app-component-a/wit, /Users/<...>/app-demo/components-cpp/app-component-a/wit-generated)
  Resolving component wit dirs for app:component-b (/Users/<...>/app-demo/components-ts/app-component-b/wit, /Users/<...>/app-demo/components-ts/app-component-b/wit-generated)
Selecting profiles, no profile was requested
  Selected default profile debug for app:component-a using template cpp
  Selected default build for app:component-b using template ts
<...>
Linking RPC
  Copying app:component-a without linking, no static WASM RPC dependencies were found
  Copying app:component-b without linking, no static WASM RPC dependencies were found

Then we can check that the components are built:

$ ls golem-temp/components
app_component_a_debug.wasm app_component_b.wasm

To deploy (add or update) or components we can use

$ golem-cli component add

or

$ golem-cli component update

in the project root folder, and the CLI will add or update all or components.

If we want to only update some components, we can do so by explicitly selecting them with the --component-name flag, or we can implicitly select them by changing our current working directory, e.g.:

$ cd components-cpp
$ golem-cli app
<...>
Components:
  app:component-a
    Selected:     yes
    Source:       /Users/noise64/workspace/examples/app-demo/components-cpp/app-component-a/golem.yaml
    Template:     cpp
    Profiles:     debug, release
  app:component-b
    Selected:     no
    Source:       /Users/noise64/workspace/examples/app-demo/components-ts/app-component-b/golem.yaml
    Template:     ts
<...>

Notice, how only app:component-a is selected in the above example, the same selection logic is used when adding or updating components.