Example

Examples of how to use your own Golem image in a requestor script

Introduction

Golem images defines a remote environment where you execute your tasks inside. They are identified either by their tag or by a hash. You can read more about Golem images in Golem Images Explained guide.

Prerequisites

Ensure you have the Yagna service installed and running, with try_golem as your configured app-key.

Running the Examples

Let's create a project folder, start a Node.js project, and add the @golem-sdk/task-executor library.

mkdir golem-example
cd golem-example
npm init
npm install @golem-sdk/task-executor

Paste the code in index.mjs located in the project folder, then run:

node index.mjs

Ways to Use Golem images

Using a Hash

A hash, in relation to Golem images, serves as a distinctive identifier formed from the image's content. They are complex, elongated strings and can become cumbersome to handle and recall, particularly in sizable projects housing various images and versions. Without tags, hashes fall short in conveying information relevant to the image's purpose or version. Due to these factors, using tags, which are readable and understandable, is generally the favored approach for dealing with images.

To illustrate the use of a hash, we can take a look at the code from the Quickstart Example

import { TaskExecutor, pinoPrettyLogger } from "@golem-sdk/task-executor";

(async () => {
  const executor = await TaskExecutor.create({
    package: "529f7fdaf1cf46ce3126eb6bbcd3b213c314fe8fe884914f5d1106d4",
    logger: pinoPrettyLogger(),
    yagnaOptions: { apiKey: "try_golem" },
  });

  try {
    const result = await executor.run(async (ctx) => (await ctx.run("node -v")).stdout);
    console.log("Task result:", result);
  } catch (err) {
    console.error("An error occurred:", err);
  } finally {
    await executor.shutdown();
  }
})();

Consider the hash 529f7fdaf1cf46ce3126eb6bbcd3b213c314fe8fe884914f5d1106d4 in the code snippet, showcasing the initialization of the TaskExecutor:

const executor = await TaskExecutor.create({
  package: '529f7fdaf1cf46ce3126eb6bbcd3b213c314fe8fe884914f5d1106d4',
  yagnaOptions: { apiKey: 'try_golem' },
})

If you've rolled out a custom Golem image and uploaded it to the registry, you can substitute this hash (529 [...] 1106d4) with your image's gvmkit-build-generated hash. If you've tagged it, you can use that tag like in the next example.

Using a tag

Tags are helpful for managing different versions of your Golem images. They make specific versions easier to identify, track, and deploy. Instead of dealing with complex hash identifiers, you may use meaningful and understandable tag names. They provide an opportunity for intuitive naming systems, enhancing project structure and promoting effective team collaboration.

import { TaskExecutor, pinoPrettyLogger } from "@golem-sdk/task-executor";

const executor = await TaskExecutor.create({
  package: "golem/alpine:latest",
  logger: pinoPrettyLogger(),
  yagnaOptions: { apiKey: "try_golem" },
});

try {
  const result = await executor.run(async (ctx) => (await ctx.run("node -v")).stdout);
  console.log("Task result:", result);
} catch (err) {
  console.error("An error occurred:", err);
} finally {
  await executor.shutdown();
}