Welcome to the new Golem Cloud Docs! 👋
Documentation
Quickstart

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.

To install golem-cli you currently need to use cargo, Rust's build tool.

To get cargo on your system, we recommend to use rustup (opens in a new tab):

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

Then you can install golem-cli with the following command:

Terminal
cargo install golem-cli

If you want to try out the hosted version of Golem you can register for the Developer Mode preview (opens in a new tab). You will then be provided with a link to download the Golem Cloud CLI.

You need to create an account and authenticate yourself before using any Golem Cloud commands. This is easy to do with Github OAuth2. Lets do it right now by using the following command:

Terminal
golem-cloud-cli account get

Once you authenticate, Golem Cloud CLI will cache an API token in a local directory named $HOME/.golem. This token will allow you to use Golem Cloud CLI without further authentication.

We will use golem-cli as opposed to golem-cloud-cli in all examples unless they are specific to Golem Cloud, but golem-cloud-cli supports all commands supported by 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.

Terminal
# 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-sqlite.yaml -O  https://raw.githubusercontent.com/golemcloud/golem/main/docker-examples/.env
 
# Start Golem with backend storage as SQLite and Redis
docker-compose -f docker-compose-sqlite.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.

If you are using the hosted version of Golem, you can skip this step.

Building an Example

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

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

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

Terminal
golem-cli new --example rust-shopping-cart --template-name shopping_cart

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

To build the newly created template you need some development tools installed. These are collected for each supported guest language on the Building Templates 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:

Terminal
cargo component build --release

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

💡

The golem-cli new command prints out the necessary steps to build your template exactly as you have to type them - using your custom template and package names and the selected example's language specific tools.

Uploading Your Template

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

Terminal
golem-cli template add --template-name shopping-cart shopping_cart.wasm

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

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

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 :

Terminal
golem-cli worker add \
  --worker-name shopping-cart-1 \
  --template-name shopping-cart

When you add a template you will see some basic information about the template 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:

Terminal
golem-cli worker invoke-and-await \
    --template-name=shopping-cart \
    --worker-name=shopping-cart-1 \
    --function=golem:template/api/initialize-cart \
    --parameters='["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.

Check the Template 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 Templates describes you can use different programming languages for building Golem templates
  • 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