Skip to main content

Running a topology

Before running a topology you first need to specify what to instantiate!

Prepare

To run the topology you first generate the runtime environment:

$ remotive-topology generate -f mytopology.instance.yaml build
Generated topology at: build/mytoplogy

This generates docker compose file, all RemotiveBroker configuration and copies all databases to the RemotiveBroker folders. Understanding these generated files is typically not necessary.

⚠️ You should not edit the generated files as they will be completely overwritten every time you run generate.

Run

Running tests

A common usecase for RemotiveTopology is to run automated test cases, typically as part of continuous integration (CI). To enable interactive mode we recommend that tests are configured using a profile. When running tests it is useful to shut down the topology after the tests have completed using the flag --abort-on-container-exit:

docker compose -f build/mytopology/docker-compose.yaml --profile tester up --abort-on-container-exit

Once you are done we recommend cleaning up the docker resources:

docker compose -f build/mytopology/docker-compose.yaml --profile tester down

Interactive mode

Another usecase is to start the topology and keep it running. This is useful when performing manual tests or when developing test cases.

docker compose -f build/mytopology/docker-compose.yaml up

Once the topology is started you can run your tests in your normal editor of choice. This works by connecting RemotiveTopology framework to the RemotiveBroker running inside the topology using port forwarding, ie connect to http://localhost:50051.

It might also be useful to enable RemotiveTopology UI.

As always, once you are done we recommend cleaning up the docker resources:

docker compose -f build/mytopology/docker-compose.yaml down

Good to know

Regenerate

⚠️ Every time you change platform or instance files the topology must be re-generated!

Changes to python code typically does not require re-generate.

Docker build

After modifying a Dockerfile you need to force docker to build, for example in interactive mode:

docker compose -f build/mytopology/docker-compose.yaml up --build

This page has more tips around docker.