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 components, create and invoke workers, and otherwise manage your Golem applications.

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

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

Recommended CLI

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

This command installs both universal golem-cli (with support for cloud and open source versions) and the cloud-specific golem-cloud-cli.

Alternative Versions

There are alternative versions of golem-cli. Please read the CLI page for more information.

Setup

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 a Profile

To specify the Golem service location, run the following command:

golem-cli init

This command starts an interactive 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 existing example:

golem-cli new --example rust-example-shopping-cart 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. Which tools you need depend on the language you are using. You can find more information on the components explainer.

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 Invoke 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:

• Read about the fundamentals of Golem
• Learn about the main concepts
• Read one of the language-specific guides to learn how to develop Golem components
• Check out how to deploy Golem to your infrastructure
• Read the details of how to invoke workers
• Learn more about the Golem CLI
• Explore operational aspects such as how worker state is persisted, what metrics and logs are available
• Check the References section for detailed information on APIs and syntaxes