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.