Quickstart

This guide will get you up and running in Golem in minutes.

Install Golem CLI

Golem CLI is a command-line application that allows you to deploy new invincible workers onto Golem.

There are precompiled binaries of golem-cli (and its other variants) for various platforms. Alternatively you can build it for yourself.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup install stable
rustup default stable

Recommended CLI version

You can download the universal version of golem-cli from the following page:

Alternatively you can build and install the universal version of golem-cli with the following command:

cargo install --features universal golem-cloud-cli

The comman above installs both universal golem-cli (with support for cloud and open source version) and cloud specific golem-cloud-cli.

Alternative CLI versions

You can download the cloud specific golem-cloud-cli without supporting OSS deployments from the following page:

Alternatively you can build and install cloud specific golem-cloud-cli without universal golem-cli with the following command:

cargo install golem-cloud-cli --bin golem-cloud-cli

You can download the open source specific golem-cli without supporting Golem Cloud from the following page:

Alternatively you can build and install open sorcce specific golem-cli without cloud profiles support with the following command:

cargo install golem-cli

Setting up Golem

To use the open source version of Golem you need to deploy it in your own infrastructure.

To get started we recommend using the Docker Compose file from the Golem Docker examples (opens in a new tab). You will need to have Docker (opens in a new tab) and Docker Compose (opens in a new tab) installed on your system.

Once you have Docker Compose installed, you can make use of docker-compose file in Golem repository to spin up Golem.

# Download an example docker-compose file along with .env file that has a few common configurations
curl -O https://raw.githubusercontent.com/golemcloud/golem/main/docker-examples/docker-compose-postgres.yaml -O  https://raw.githubusercontent.com/golemcloud/golem/main/docker-examples/.env
 
# Start Golem with backend storage as PostgreSQL and Redis
docker-compose -f docker-compose-postgres.yaml up

Note that, here we are making use of an example docker-compose file. You may need to modify it to suit your needs, or refer other examples in Golem repository (opens in a new tab). That said, the example docker-compose file along with .env file should be enough to get you started.

If you are running into any port conflicts you can modify the .env file that was downloaded as part of the above curl command.

See also deployment page for additional deployment options.

Creating CLI profile

To specify Golem service location run the following command:

golem-cli init

This command starts an iteractive configuration process. For non-interactive options - see Golem CLI page.

On the first step you'll see 3 options:

• Golem Default. Use this options for default local docker compose installation.
• Golem. Use this option in case of a customised Golem installation, i.e. a custom GOLEM_ROUTER_PORT in .env file.
• Golem Cloud. Use this option for a hosted version of Golem.

If you can't see Golem Cloud option - you are using an open source specific version of golem-cli instead of universal golem-cli.

Building an Example

Golem runs components that are WebAssembly programs. Components are like applications, except they may expose functions that can be called externally.

To deploy to Golem, you must first build a component using any programming language and toolchain that can build WebAssembly components.

To get started quickly, you can use Golem CLI to create a component from an example:

golem-cli new --example rust-shopping-cart --component-name shopping_cart

This will generate a new shopping_cart directory in the current directory with the example for your component.

To build the newly created component you need some development tools installed. These are collected for each supported guest language on the Building Components page. For the above example, please read the Rust specific instructions to set up cargo-component.

Once you have that, navigate to the shopping_cart, and run:

cargo component build --release

This will write the resulting component to shopping_cart/target/wasm32-wasi/release/shopping_cart.wasm.

Uploading Your Component

To upload your component to Golem, you can use the component add command. Navigate to shopping_cart/target/wasm32-wasi/release and then do:

golem-cli component add --component-name shopping-cart shopping_cart.wasm

Uploading a component to Golem does not actually execute the component. Instead, it only makes it available for execution to Golem .

Every separate execution of your component is referred to as a worker based on that component.

Create Workers

In Golem, every worker has a unique id, which is arbitrary text that you define. If you don't need a meaningful id for workers, you can generate a UUID.

Once you have chosen a worker id, you can launch the worker either explicitly, or by invoking any function on the worker (for example, a “main” function).

Here, we creating a new worker shopping-cart-1 :

golem-cli worker add \
  --worker-name shopping-cart-1 \
  --component-name shopping-cart

When you add a component you will see some basic information about the component such as its name, unique identifier, version, and size. In addition, you will see a list of exports. These are the public API of your worker and can be used to call it with the CLI or REST API, as we will see below.

Invoking Workers

Thanks to the WebAssembly component model, your Golem applications are not just an executable. Rather, they may export functions that can be called from the outside. Exported functions allow your workers to be given instructions or queried for their state.

Here, we invoke the function initialize_cart on the worker with a single string parameter:

golem-cli worker invoke-and-await \
    --component-name shopping-cart \
    --worker-name shopping-cart-1 \
    --function 'golem:component/api.{initialize-cart}' \
    --arg '"test-user"'

If a worker of the specified name has not been created, then when you attempt to invoke a function on the worker, it will first be created.

The parameters are either listed one by one with separate --arg options using the WAVE format (opens in a new tab), or as a single JSON array using --parameters.

Check the Component interface section to learn about how to figure out the function name and how to encode your parameters in JSON.

Next Steps

In this guide, you have learned how to build and deploy invincible serverless workers on Golem, and seen how you can interact with them as they execute.

Take your next steps with Golem by exploring the following resources:

• Building Components describes you can use different programming languages for building Golem components
• Promises are a way to block your program until an external condition fulfills it.
• The Golem CLI page lists all the commands available on Golem's command line interface
• Golem can also be controlled using its REST API
• Read the FAQ page for frequently asked questions