For a quick test using Docker

Edit on GitHub

This page describe how to perform a quick test of Zenoh, using a Docker image.

Run Zenoh router in a Docker container

The Zenoh router is also available in a Docker image. You can deploy a single instance on your local host just running:

docker run --init -p 7447:7447/tcp -p 8000:8000/tcp eclipse/zenoh

The ports used by Zenoh are the following:

  • 7447/tcp : the Zenoh protocol via TCP
  • 8000/tcp : the Zenoh REST API

⚠️ WARNING ⚠️: Docker doesn’t support UDP multicast between a container and its host (see cases moby/moby#23659, moby/libnetwork#2397 or moby/libnetwork#552). The only case where it works is on Linux using the --net=host option to make the container to share the host’s networking space (i.e. run: docker run --init --net=host eclipse/zenoh).
The implication of not having UDP multicast working for the Zenoh router is that you need to configure your Zenoh applications (peer or client) with the router’s locator as peer:

  • running the examples we provide, just add the option: -e tcp/localhost:7447
  • writing your own Zenoh application, you need to add a connect: {endpoints: ["tcp/localhost:7447"]}} configuration when initiating the Zenoh API

Adding plugins and backends to the container

The Zenoh router supports the dynamic loading of plugins libraries (at startup) and backends libraries (during runtime).
See the relevant chapters for more details about plugins and backends:

⚠️ WARNING ⚠️: To be compatible with Zenoh in Docker, the libraries must be compiled for x86_64-unknown-linux-musl target. Look for .tgz filenames with this extension when downloading plugins or backends from the Eclipse zenoh download space.

By default the Zenoh router will search for plugins and backends libraries to load in ~/.zenoh/lib. Thus, to make it able to find the libraries, you can copy them into a zenoh-docker/lib directory on your local host and mount the zenoh-docker directory as a volume in your container targeting /root/.zenoh.

Example:

docker run --init -p 7447:7447/tcp -p 8000:8000/tcp -v $(pwd)/zenoh-docker:/root/.zenoh eclipse/zenoh

Example of a Docker compose file (also configuring Zenoh log level to “debug”):

version: "3.9"
services:
  zenoh:
    image: eclipse/zenoh
    restart: unless-stopped
    ports:
      - 7447:7447
      - 8000:8000
    volumes:
      - ./zenoh_docker:/root/.zenoh
    environment:
      - RUST_LOG=debug

First tests using the REST API

The complete Eclipse zenoh’s key/value space is accessible through the REST API, using regular HTTP GET, PUT and DELETE methods. In those examples, we use the curl command line tool.

Managing the admin space

  • Get info of the local Zenoh router:
    curl http://localhost:8000/@/router/local
  • Add a memory storage on demo/example/**:
    curl -X PUT -H 'content-type:application/json' -d '{key_expr:"demo/example/**", volume: "memory"}' http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo
  • Get the storages of the local router (should return the “demo” storage that has just been created):
    curl 'http://localhost:8000/@/router/local/status/plugins/storage_manager/storages/*'

Put/Get into Zenoh

Assuming the memory storage has been added, as described above, you can now:

  • Put a key/value into Zenoh:
curl -X PUT -H 'content-type:text/plain' -d 'Hello World!' http://localhost:8000/demo/example/test
  • Retrieve the key/value:
curl http://localhost:8000/demo/example/test
  • Remove the key value
curl -X DELETE http://localhost:8000/demo/example/test

Your first app in Python

Now you can see how to build your first Zenoh application in Python.

Pick your programming language

If you prefer, you could also have a look to the examples/zenoh directory we provide in each Zenoh API:

Next up: Troubleshooting