Golem Application Manifest

The Golem Application Manifest document format is used by golem, usually stored in files named golem.yaml, and they are the intended way to define, build, deploy and manage Golem Applications and Environments.

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 arguments, but the recommended way to use them is with auto discovery mode: when golem 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 component templates

Golem projects can be created with golem new command. This creates a new application that may consist of multiple components. To add a new component to an existing application, use golem component new. E.g.: let's add a new c and ts component in a new and empty directory:

golem new myapp rust
cd myapp
golem component new rust app:component-a
golem component new ts app:component-b

When using the app new command, it will create:

common directory for the given language (common-rust 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-rust and components-ts)

Let's rename one of the generated agents, so they are unique for the deployment. In components-ts/app-component-b/src/main.ts change:

- class CounterAgent extends BaseAgent {
+ class OtherCounterAgent extends BaseAgent {

and in components-ts/app-component-b/golem.yaml:

-             let agent = counter-agent(name);
+             let agent = other-counter-agent(name);

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

$ golem
 
Golem Command Line Interface
 
Usage: golem [OPTIONS] <COMMAND>
 
Commands:
  new               Create a new application
  build             Build all or selected components in the application
  repl              Start Rib REPL for a selected component
  deploy            Deploy application
  clean             Clean all components in the application or by selection
  update-agents     Try to automatically update all existing agents of the application to the latest version
  redeploy-agents   Redeploy all agents of the application using the latest version
  diagnose          Diagnose possible tooling problems
  list-agent-types  List all the deployed agent types
  exec              Execute custom, application manifest defined commands
  environment       Manage environments
  component         Manage components
  agent             Invoke and manage agents
  api               Manage API gateway objects
  plugin            Manage plugins
  profile           Manage global CLI profiles
  server            Run and manage the local Golem server
  cloud             Manage Golem Cloud accounts and projects
  completion        Generate shell completion
  help              Print this message or the help of the given subcommand(s)
 
Options:
  -F, --format <FORMAT>
          Output format, defaults to text, unless specified by the selected profile
  -E, --environment <ENVIRONMENT>
          Select Golem environment by name
  -L, --local
          Select" local" environment from the manifest, or "local" profile
  -C, --cloud
          Select "cloud" environment from the manifest, or "cloud" profile
  -A, --app-manifest-path <APP_MANIFEST_PATH>
          Custom path to the root application manifest (golem.yaml)
  -X, --disable-app-manifest-discovery
          Disable automatic searching for application manifests
  -P, --preset <PRESET>
          Select custom component presets
      --profile <PROFILE>
          Select Golem profile by name
      --config-dir <CONFIG_DIR>
          Custom path to the config directory (defaults to $HOME/.golem)
  -Y, --yes
          Automatically answer "yes" to any interactive confirm questions
      --show-sensitive
          Disables filtering of potentially sensitive use values in text mode (e.g. component environment variable values)
      --dev-mode
          Enable experimental, development-only features
      --template-group <TEMPLATE_GROUP>
          Switch to experimental or development-only template groups
  -v, --verbose...
          Increase logging verbosity
  -q, --quiet...
          Decrease logging verbosity
  -h, --help
          Print help
  -V, --version
          Print version
 
Application environments:
  cloud
    Selected: no
    Server:   cloud - builtin (https://release.api.golem.cloud)
    Presets:  release
 
  local
    Selected: yes
    Server:   local - builtin (http://localhost:9881)
    Presets:  debug
 
Application components:
  app:component-a
    Selected:     yes
    Source:       /Users/noise64/workspace/golem-demo/myapp/components-rust/app-component-a/golem.yaml
    Layers:       rust, rust[debug], app:component-a
 
  app:component-b
    Selected:     yes
    Source:       /Users/noise64/workspace/golem-demo/myapp/components-ts/app-component-b/golem.yaml
    Layers:       ts, app:component-b
 
Application API definitions:
  app-component-a-api@0.0.1
  app-component-b-api@0.0.1
 
Application API deployments for environment local:
  myapp.localhost:9006
    app-component-a-api
    app-component-b-api
 
Application custom commands:
  cargo-clean
  ts-npm-install

Starting the local development server

The golem CLI also includes a local development server that can be used to quickly develop, deploy, test and debug Golem applications locally. To start the server use:

golem server run

The above command will quickly boot the server, and then it will keep logging to the terminal, so let's switch to another terminal to continue with building and deploying our application..

Building and deploying the application

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, and golem itself will automatically run it before a build. Let's see an example for both:

$ golem exec npm-install
<..>
$ golem build
Collecting sources
  Found sources: /Users/<...>/app-demo/common-rust/golem.yaml, /Users/<...>/app-demo/common-ts/golem.yaml, /Users/<...>/app-demo/components-rust/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-rust/app-component-a/wit, /Users/<...>/app-demo/components-rust/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 the application, including all the components, we can use

golem deploy

in the application root folder, and the CLI will apply all changes required.

Note that golem deploy will also always implicitly check for source changes, and based on that will automatically build any changed components, so usually we can just run golem deploy.

If we want to only build 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-rust
$ golem
<...>
Components:
  app:component-a
    Selected:     yes
    Source:       /Users/noise64/workspace/examples/app-demo/components-rust/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 building. On the other hand, deploying will always deploy the whole application atomically, so it is ensured that all our agents are up-to-date.

When developing locally, it is often useful to drop all our existing durable agents and have a fresh clean environment for testing. For this, use:

golem deploy --reset

Targeting Golem Cloud, or other environments

By default, most golem commands will target the local Golem server.

To access Golem's own hosted Golem Cloud (or other custom installations), we can simply use the same commands as before but select the cloud environment with one of the following ways:

# Explicitly selecting the cloud (or a custom) environment
golem --enviroment cloud deploy
golem -E cloud deploy
 
# Using the convenience cloud flag:
golem --cloud deploy
golem -C build
 
# Or by using environment variables, which can be useful in CI/CD pipelines:
export GOLEM_ENVIRONMENT=cloud
golem deploy

For more information see the next seection about Environments and Profiles.

CLI Environments and Profiles