Testing a Golem image
How to run a .gvmi image locally for the sake of testing and debugging
In this tutorial we're going to explore
ya-runtime-dbg, a tool built specifically for debugging user-built images.
This tutorial assumes that you're already familiar with Docker and the basics of building a Golem application.
ya-runtime-dbgis currently available for Linux only.
sudo dpkg -i path/to/.../ya-runtime-dbg_v0.2.3_amd64.deb
If you don't want to (or cannot) use a
.debpackage you can also download a pre-built binary (
.tar.gzfile in the most recent GitHub release).
ya-runtime-dbgrequires one of the available Golem runtimes to be available on your system.
A set of default runtimes can be installed by the
curl -sSf https://join.golem.network/as-provider | bash -
After using the installer your runtime binaries should be present under
~/.local/lib/yagna/plugins(again, we're assuming Linux as it's the only supported platform for
Later on we're going to see how to specify the runtime to be used by the debugger.
Let's now see how we can use
ya-runtime-dbgtogether with our image. We can learn about the program's required arguments by calling
ya-runtime-dbg [FLAGS] [OPTIONS] --runtime <runtime> --task-package <task-package> --workdir <workdir> [varargs]...
The program has three mandatory arguments:
--runtimepath to the Golem runtime we want to use,
--task-packagepath to the package (i.e.
.gvmiimage) we'd like to debug,
--workdirpath to the directory that will store directories mounted as volumes inside the image.
Please note: the program does not support relative paths (i.e. paths relative to your shell's present directory).
Let's now run the debugger supplying it with appropriate parameters:
--runtime ~/.local/lib/yagna/plugins/ya-runtime-vm/ya-runtime-vm \
--task-package ~/.../docker-runtime-dbg-example-latest-be31909af5.gvmi \
The command is split into multiple lines using
\so that it's easier to read. Some remarks related to the above call:
- 1.The path in
--task-packageneeds to be changed so that it points to where you built your
/tmp/workdiris an example path, it may not exist on your system. You can create it by calling
mkdir /tmp/workdiror use some other location.
Running the command should produce output similar to this:
[INFO] Entering prompt, press C-d to exit
Followed by a prompt character (
▶). This indicates the debugger is now ready to be used!
With the debugger running we now have full access to our virtual machine!
The debugger provides us with an interactive shell which, by default, uses
bash(indicated by the name next to the prompt character). This means we can use regular command line tools, for example:
bash ▶ pwd
pwd(present working directory) returns
/golem/work, matching the path we specified in
WORKDIRin our original
This interactive prompt gives us full access to the virtual machine. For example, we could run the program or script that is normally executed by a provider.
Now, let's see how we can interact with the mounted volumes. First off, let's take a closer look at the startup output from the debugger (specifically, the
volsfield from the second line):
This tells us about the directory mapping between our host machine and the virtual machine. The host directories are created under the path we specified as
--workdirwhen starting the debugger (in our case it's
Let's say we'd like to provide some data to the VM. We can do so by creating a file in the host directory that's mapped to
/golem/inputinside the VM. Looking at the mapping definition above, this directory is going to be
echo "stuff" > /tmp/workdir/vol-32e25157-5865-4fd2-9d35-909cd9893682/data.txt
With the debugger still running, let's now verify that this file is accessible inside our VM. Using the debugger prompt let's issue the below command:
bash ▶ cat /golem/input/data.txt
Success! Our input data is there and can be read by the VM.
ya-runtime-dbgis going to create new directories for volumes in each run.
Once you're done debugging or want to restart the VM, press
Ctrl+Dwhile in the debugger prompt.
Having issues? Make sure to take a look at our VM runtime FAQ:
ya-runtime-dbgprovides us with the exact same environment a provider would use to execute our image. This allows for more accurate testing compared to running the original Docker image manually.
Here are some other advantages of using this debugger while developing a Golem application:
- shorter iteration times while working on the payload for the provider,
- isolated testing: no need to run the entire application,
- fully controlled, local environment with access to mounted volumes,
- full shell access to the virtual machine.