Hello World Full Tutorial

In this tutorial, we will develop the code example from the Hello_World Quick Start in detail.

You will learn how to write your own hyveOS application code and publish it to a Docker Container Registry.

We are going to develop it in Python — it will be asynchronous programming. If you like, you can open Python’s asyncio documentation next to this tutorial should you want to see some concepts of asynchronous programming in Python.

Final application code

You can always jump back here to view the entire application code if you want to understand where you are exactly.

main.py

1
import asyncio
2
from hyveos_sdk import Connection
3

4

5
async def wait_for_peers(discovery):
6
    await asyncio.sleep(5)
7
    async for event in discovery.discovery_events():
8
        if event is not None:
9
            print(f"Discovered a peer: {event}")
10
            break
11

12

13
async def node(topic):
14
    print("--- APPLICATION SCRIPT is RUNNING ---")
15
    async with Connection() as connection:
16
        discovery = connection.get_discovery_service()
17
        gossip_sub = connection.get_gossip_sub_service()
18

19
        own_id = await discovery.get_own_id()
20
        print(f"Node {own_id} has started.")
21

22
        while True:
23
            await wait_for_peers(discovery)
24

25
            stream = await gossip_sub.subscribe(topic)
26

27
            await asyncio.sleep(12)
28

29
            message = f"Hello from {own_id}"
30
            await gossip_sub.publish(message, topic)
31

32
            async for msg in stream:
33
                if msg != message:
34
                    print(f"Node {own_id} received: {msg}")
35
                    break
36

37

38
async def main():
39
    topic = "greetings"
40
    await node(topic)
41

42

43
if __name__ == "__main__":
44
    asyncio.run(main())

Setup

Directory structure

First, create the following directory tree:

Directoryhello_world
- Dockerfile
- main.py
- pyproject.toml

Dependencies

We recommend setting up a pyproject.toml file in order to manage dependecies cleanly. It should have the following form and content: You will need Python 3.11 or above and the latest version of the hyveOS SDK. Also note the arguments in [build-system].

1
[tool.poetry]
2
name = "hello_world"
3
version = "0.1.0"
4
description = "P2P Hello World messaging from node to node"
5
authors = ["Author <[email protected]>"]
6
license = "MIT"
7

8
[tool.poetry.dependencies]
9
python = "^3.11"
10
hyveos-sdk = "^0.1.0"
11

12
[build-system]
13
requires = ["poetry-core>=1.0.0"]
14
build-backend = "poetry.core.masonry.api"

Setting up a hyveOS `asyncio` program

Imports

You will have to import our SDK hyveos_sdk and the asyncio library.

1
import asyncio
2
from hyveos_sdk import Connection

Entry point

The entry point will start to run the coroutine. In main(), we define the topic "greetings", which we are going to give to each node to subscribe to. The Pub/Sub mechanism will be used under "greetings" in this code example.

1
async def main():
2
    topic = "greetings"
3
    await node(topic)
4

5
if __name__ == "__main__":
6
    asyncio.run(main())

Node discovery and message publication/subscription

Now, let’s develop the main logic of the application.

The first step is to open an async Connection() context through hyveOS, and then get the services you need.

In our case, we need two services:
discovery so that each node can discover its neighbor by id for it to know that someone will be listening if it publishes a message into the Pub/sub.
The gossip_sub service, our Pub/sub, is the second service here.

1
async def node(topic):
2

3
    async with Connection() as connection:
4
        discovery = connection.get_discovery_service()
5
        gossip_sub = connection.get_gossip_sub_service()

Let us also quickly notify the programmer about the id of the current node by logging it, enabling easier troubleshooting. Always make sure to know the id of the node you currently care about!

1
async def node(topic):
2

3
    async with Connection() as connection:
4
        // continuing the last code block
5

6
        own_id = await discovery.get_own_id()
7
        print(f"Node {own_id} has started.")

After that, make sure each node finds its neighbor. If they are not found in this scenario with two nodes only, you might risk publishing to a topic where you cannot have made sure that the two nodes have seen each other. We loop through the rest of the section of the code. In order for the two nodes to find each other, write the function wait_for_peers() which will be awaited for each node. It will be periodically checking for a new event regarding the discovery of a new peer.

1
async def node(topic):
2

3
    async with Connection() as connection:
4
        // continuing the last code block
5

6
        while True:
7
            await wait_for_peers(discovery)

The function itself takes the discovery service to wait for an event. In this case, the event tells us that a new node was discovered. If you wanted to make it clear, you should check whether it was a node discovered or node lost event. However, in this small tutorial, we have a setup where they first have to establish mutual sight of each other—they weren’t in a neighbor relationship prior—, so we know the event is a node discovered event.

1
async def wait_for_peers(discovery):
2
    await asyncio.sleep(5)
3
    async for event in discovery.discovery_events():
4
        if event is not None:
5
            print(f"Discovered a peer: {event}")
6
            break

Moving forward, we can finally use the gossip_sub service.

1
async def node(topic):
2

3
    async with Connection() as connection:
4
        // ...
5

6
        // continuing the last code block
7
        while True:
8
            await wait_for_peers(discovery)
9

10
            stream = await gossip_sub.subscribe(topic)

subscribe() returns a stream. We will later be listening on this stream for messages published into it.

Let’s finally create the own message from the own node, and publish it into the Pub/sub. Be sure to await gossip_sub.publish()!

1
async def node(topic):
2

3
    async with Connection() as connection:
4
        // ...
5

6
        while True:
7
            // continuing the last code block
8

9
            message = f"Hello from {own_id}"
10
            await gossip_sub.publish(message, topic)

Remember the stream from the second to last code block? Now, we need to read the previously published message (coming from the other node) from that stream. Also, you don’t want to retreive your own message from the stream so there is an if statement for that.

1
async def node(topic):
2

3
    async with Connection() as connection:
4
        // ...
5

6
        while True:
7
            // continuing the last code block
8

9
            async for msg in stream:
10
                if msg != message:
11
                    print(f"Node {own_id} received: {msg}")
12
                    break

So that’s how you finally would receive the message. To view the entire node(topic) method, expand the code beneath:

function node(topic)

1
...
2

3
async def node(topic):
4
    print("--- APPLICATION SCRIPT is RUNNING ---")
5
    async with Connection() as connection:
6
        discovery = connection.get_discovery_service()
7
        gossip_sub = connection.get_gossip_sub_service()
8

9
        own_id = await discovery.get_own_id()
10
        print(f"Node {own_id} has started.")
11

12
        while True:
13
            await wait_for_peers(discovery)
14

15
            stream = await gossip_sub.subscribe(topic)
16

17
            await asyncio.sleep(12)
18

19
            message = f"Hello from {own_id}"
20
            await gossip_sub.publish(message, topic)
21

22
            async for msg in stream:
23
                if msg != message:
24
                    print(f"Node {own_id} received: {msg}")
25
                    break
26

27

28
...

That’s it! You have implemented the main logic of our simple program. Next, we need to build a Docker image out of the code and deploy the images on each end node.

Deployment

In hyveOS, all application code will be deployed through Docker containers. This enables easy cross-operability, reuse of images, and sandboxed deployment.

Start deployment by writing the Docker file.

Dockerizing

1
ARG BRANCH=main
2

3
FROM ghcr.io/p2p-industries/hyveos-base-python:${BRANCH}
4

5
RUN apt-get update
6
RUN apt-get install --yes build-essential
7

8
WORKDIR /app/hello_world
9

10
COPY poetry.lock poetry.lock
11
COPY pyproject.toml pyproject.toml
12

13
RUN poetry add /app/python/sdks/dist/*.whl
14
RUN poetry install --no-root
15

16
COPY main.py main.py
17

18
ENV PYTHONUNBUFFERED=1
19

20
CMD ["poetry", "run", "python", "main.py"]

Next up, build the image. Make sure that the working directory is hello_world. Also, publish the image to a Container Registry of your choice. We recommend using GitHub Container Registry.

Deploying and starting at the node

docker pull <IMAGE_AT_YOUR_CONTAINER_REGISTRY>

We are now using hyvectl to deploy the Hello World application to both nodes only from node0.

As initial deployment can take a few seconds, you want to begin with deploying to node 1, from node0.

To deploy and start the application on node1 through node 0, run on node0 first:

hyvectl hyve start <IMAGE_AT_YOUR_CONTAINER_REGISTRY> <ID>

where <IMAGE_AT_YOUR_CONTAINER_REGISTRY> is the link to your container registry, and <ID> is the ID of node 1, which you can find using the command

hyvectl whoami

at node 1.

To then start the application on node0, run on node0

hyvectl hyve start <IMAGE_AT_YOUR_CONTAINER_REGISTRY>

Message outputs in the consoles

As an intermediary step, you can check the output of the application on each node.

sudo docker container ls

On each node, the container ID of the running container is returned.

Grab <ID1> and <ID2> of the container on node0 and node1, respectively.

To see the output on your node, run the following command with the respective container ID:

sudo docker logs <ID1>

If you managed to work out everything smoothly, you should see outputs of the following form on each node:

Node 0
Node 1

1
--- APPLICATION SCRIPT is RUNNING ---
2
Node 12D3KooWMm4qMVTHFwCgjbxsEJdScBZ9uBpmKzSiXL4q8J6i54VP has started.
3
Discovered a peer: init {
4
    peers {
5
        peer_id: "12D3KooWHcLfA7Ux82gMz5VDZM1QaDqaoF7RpnQrDMukFe3EPNdh"
6
    }
7
}
8

9
Node 12D3KooWMm4qMVTHFwCgjbxsEJdScBZ9uBpmKzSiXL4q8J6i54VP received: propagation_source {
10
    peer_id: "12D3KooWHcLfA7Ux82gMz5VDZM1QaDqaoF7RpnQrDMukFe3EPNdh"
11
}
12
source {
13
    peer_id: "12D3KooWHcLfA7Ux82gMz5VDZM1QaDqaoF7RpnQrDMukFe3EPNdh"
14
}
15
msg {
16
    data {
17
        data: "Hello from 12D3KooWHcLfA7Ux82gMz5VDZM1QaDqaoF7RpnQrDMukFe3EPNdh"
18
    }
19
    topic {
20
        topic: "script/greetings"
21
    }
22
}
23
msg_id {
24
    id: "12D3KooWHcLfA7Ux82gMz5VDZM1QaDqaoF7RpnQrDMukFe3EPNdh1736669735872847049"
25
}

1
--- APPLICATION SCRIPT is RUNNING ---
2
Node 12D3KooWHcLfA7Ux82gMz5VDZM1QaDqaoF7RpnQrDMukFe3EPNdh has started.
3
Discovered a peer: init {
4
    peers {
5
        peer_id: "12D3KooWMm4qMVTHFwCgjbxsEJdScBZ9uBpmKzSiXL4q8J6i54VP"
6
    }
7
}
8

9
Node 12D3KooWHcLfA7Ux82gMz5VDZM1QaDqaoF7RpnQrDMukFe3EPNdh received: propagation_source {
10
    peer_id: "12D3KooWMm4qMVTHFwCgjbxsEJdScBZ9uBpmKzSiXL4q8J6i54VP"
11
}
12
source {
13
    peer_id: "12D3KooWMm4qMVTHFwCgjbxsEJdScBZ9uBpmKzSiXL4q8J6i54VP"
14
}
15
msg {
16
    data {
17
        data: "Hello from 12D3KooWMm4qMVTHFwCgjbxsEJdScBZ9uBpmKzSiXL4q8J6i54VP"
18
    }
19
    topic {
20
        topic: "script/greetings"
21
    }
22
}
23
msg_id {
24
    id: "12D3KooWMm4qMVTHFwCgjbxsEJdScBZ9uBpmKzSiXL4q8J6i54VP1736707432415633050"
25
}

The messages periodically repeat starting with the Discovered a peer event.

That’s it! You have successfully used hyveOS to send a message from node1 to node0 and vice versa. Make sure you finish off with terminating the loop as seen in the next box.

Terminate the Loop

As the program is looping, you need to terminate the Docker Container. You might need sudo rights to run the commands.

Check all running containers

docker ps

Identify the CONTAINER ID of the container you want to stop.

Stop the container

docker stop <container_ID_or_name>

This sends a graceful stop signal, giving the container a chance to shut down properly.

Summary

We have seen how to set up a simple application program in Python enabling the sending of messages from one node to another and vice versa. The important steps are:

take care of dependencies
write async code with the asyncio library—take care of async and await properly!
let the nodes discover each other
after that, make sure that all nodes first subscribe to the Pub/sub topic and only afterwards start publishing messages
deploy the application scripts with Docker
run the images on each node