How to run custom application on SONM

This little guide will help experienced SONM users to run custom applications on SONM suppliers. If you don’t know anything about SONM, better start with reading docs.

You need to pass KYC3, without it you can only run tasks from allowed list.

As an example for this guide I will use SONM Community Telegram Bot, at the end you should be able to build and run it on SONM.

Build an image

Docker has great documentation and you can read this manual to get basic understanding of image build process and best practices for writing Dockerfile.

So why do we need this guide if Docker has all the documentation?

Yes, you can run any docker image on SONM, but if they use command line arguments to configure application runtime or pass arguments to deamon inside container, then you can’t use it. SONM tasks don’t accept arguments from command line and the only way to pass arguments into container is to use environment variables.

Dockerfile

Dockerfile contains list of commands that will prepare environment for your application, you can install anything you want/need here.

Our bot is written in python, so we will use python base image from Docker Hub and pip to install needed python libraries.

Here is Dockerfile from bot repo:

FROM python:3-slim
WORKDIR /usr/src/app
COPY . .
RUN pip install python-telegram-bot seaborn pandas numpy scipy
RUN chmod +x init.sh
ENTRYPOINT ["./init.sh"]

As I mentioned, we can pass arguments to application inside container only via environment variables, so we need to have some wrapper that will turn them into command line arguments.

What does it mean? Usually to run docker image you need to set arguments for application from command line like this:

$ docker run <someimage> [ARGS]

To make this work for SONM we can write simple bash script that will get arguments from environment and append it to application.

ENTRYPOINT bash script could look like this:

#!/usr/bin/env bash
exec python ./start.py "$COMMANDVAR"

Now you can add arguments to environment variable $COMMANDVAR and they will be added as command line arguments to application.

To play with docker environment variables you can use command like this:

$ docker run -e "COMMANDVAR=--verbose" <someimage>

For simplicity of an example scripts, they don’t have any validation of inputs, so they could be not safe to use as is.

Our bot doesn’t use any command line arguments, but needs to set telegram token in configuration file. Here is init.sh from bot repo that uses $TOKEN variable from environment:

#!/usr/bin/env bash
if [ ! -z "$TOKEN" ]; then
  echo "[+] Using provided Telegram token."
  cat config/telegram.json.template|sed "s/ADD_BOT_TOKEN_HERE/$TOKEN/g" > config/telegram.json
else
  echo "[-] No Telegram token provided."
  exit 1
fi
exec python ./start.py

Application

SONM Community Telegram Bot contains all necessary code, so you can just clone this repo and proceed further.

$ git clone https://github.com/taskula/sonm-community-telegram-bot

Build

Build process is the same as for usual docker images.

$ cd sonm-community-telegram-bot
$ docker build -t sonm-community-telegram-bot .

Run

If you want to test with environment variables, you can just set them with -e flag.

$ docker run -e TOKEN=YOUR_TOKEN_HERE sonm-community-telegram-bot

Docker Hub

Ok, we’ve built our image and we’re able to run it, now we need to make it accessible from outside. You can setup you own registry, Docker Hub or any other available registry.

We will stick to Docker Hub, it’s the easiest way and you can use public or private repos for this, task files support both.

Login to Docker Hub

If you don’t have an account on Docker Hub, it’s time to register one. Once you have an account, you need to login from command line, just run:

$ docker login

Tag build

Before uploading image to Hub, we need to tag it, I won’t go into detail about this process, you can read about it here, so we will use most basic variation:

$ docker tag sonm-community-telegram-bot <DockerHubLogin>/sonm-community-telegram-bot

Push image

After setting the tag, we can just upload our image and proceed to write SONM task file.

$ docker push <DockerHubLogin>/sonm-community-telegram-bot

Automated builds

If your project is open-sourced on GitHub, I suggest you to read about automated builds on Docker Hub, that will make the process of building new versions of image much easier.

Running a task

You must have an active deal to run task on, if you know nothing about SONM task files, read this. If you don’t know how to get a deal read this.

Our application is pretty simple and task.yaml will look like:

container:
  image: <DockerHubLogin>/sonm-community-telegram-bot
  env:
    TOKEN: add_your_telegram_token_here

This task file doesn’t cover all options that you can set, but you can find them in this example.

To run this task, you can just type:

$ sonmcli task start <dealID> task.yaml

Summary

Congratulations, now you know how to run any custom application on SONM!

If you have any questions, drop me a line.