Example

Golem-Workers Hello Service Example

This example demonstrates how to run a simple "Hello" service using Golem-Workers. Unlike the Stable Diffusion example, this service does not require a GPU and can be run for free on the testnet. It is designed as a basic introduction for new users, with more advanced examples like the Stable Diffusion tutorial available for further exploration.

Prerequisites

We will be using curl (for Windows users consider PowerShell command Invoke-WebRequest instead) to interact with the Golem-Workers API, which runs on localhost:8000 (see Getting started if it is not). All API requests will use JSON data to configure and manage the Golem-Workers service.

The JSON files used in this article can be found in the repository under the directory examples/hello-example. Make sure you run the curl commands from within this repository to ensure the paths to the JSON files are correct.

Feel free to experiment and modify the JSON files if you’d like to adjust configurations or explore different setups.

1. Create a Cluster

To start, create a cluster with any name you choose (cluster_id). For this example, we'll use example as the cluster_id.

curl --location 'http://localhost:8000/create-cluster' \
--header 'Content-Type: application/json' \
--data @create-cluster.json

This is the json file you have just used (also available on GitHub):

{
    "cluster_id": "example",
    "budget_types": {
        "default": {
            "budget": {
                "golem_workers.budgets.AveragePerCpuUsageLinearModelBudget": {
                    "average_cpu_load": 1,
                    "average_duration_hours": 0.5,
                    "average_max_cost": 1.5
                }
            },
            "scope": "cluster"
        }
    },
    "network_types": {
        "default": {
            "ip": "192.168.0.1/16"
        }
    },
    "node_types": {
        "default": {
            "market_config": {
                "filters": [
                    {
                        "golem_reputation.ProviderBlacklistPlugin": {
                            "payment_network": "holesky"
                        }
                    }
                ],
                "sorters": [
                    {
                        "golem_reputation.ReputationScorer": {
                            "payment_network": "holesky"
                        }
                    }
                ]
            }
        }
    }
}

create-cluster JSON explained

  • Budget: We set up a budget using golem_workers.budgets.AveragePerCpuUsageLinearModelBudget to limit costs. In this example, we specify that the node should not cost more than 1.5 tGLM, assuming it runs for 0.5 hours with 1 CPU in use.

  • Network: The network configuration sets up an IP range for the cluster nodes.

2. Create a Node

Next, create a node using the Hello Service image from the Golem Registry. This service listens on port 80 and simply returns "Hello" when accessed.

curl --location 'http://localhost:8000/create-node' \
--header 'Content-Type: application/json' \
--data @create-node.json

This is the json file you have just used (also available on GitHub):

{
    "cluster_id": "example",
    "node_networks": {
        "default": {}
    },
    "node_config": {
        "market_config": {
            "demand": {
                "payloads": [
                    {
                        "golem_workers.payloads.ClusterNodePayload": {
                            "image_tag": "modelserve/echo-test:2"
                        }
                    }
                ]
            }
        },
        "on_start_commands": [
            {
                "golem_workers.work.deploy_and_start_activity": {
                    "deploy_timeout_minutes": 60
                }
            },
            {
                "golem_workers.work.run_in_shell": [
                    [
                        "nginx"
                    ]
                ]
            }
        ],
        "sidecars": [
            {
                "golem_workers.sidecars.WebsocatPortTunnelSidecar": {
                    "network_name": "default",
                    "local_port": "8080",
                    "remote_port": "80"
                }
            }
        ]
    }
}

create-node JSON explained

  • Image: The node runs the Hello Service image modelserve/echo-test:2, which is a simple NGINX-based service that returns "Hello" on port 80.
  • Commands: We deploy the node and start the service using NGINX.
  • Port Forwarding: We forward port 80 on the node to localhost:8080 on your machine, allowing you to access the service locally.

3. Get the cluster's status

Next, you should wait until your node is up. Check the cluster and node state with a call to get-cluster:

curl --location 'http://localhost:8000/get-cluster' \
--header 'Content-Type: application/json' \
--data @get-cluster.json

This is the json file you have just used (also available on GitHub):

{
    "cluster_id": "example"
}

4. Access the Hello Service

Once the node is started, open your browser and navigate to http://localhost:8080. You should see the message Hello displayed.

5. Stop the Cluster

After you're done, you should shut down the cluster using the following command:

curl --location 'http://localhost:8000/delete-cluster' \
--header 'Content-Type: application/json' \
--data @delete-cluster.json

This is the json file you have just used (also available on GitHub):

{
    "cluster_id": "example"
}

For more advanced example of deploying GPU-based nodes to run Stable Diffusion, check out this article.

Was this helpful?