Basic Usage - robocup-logistics/rcll-get-started GitHub Wiki
This repository provides the software of the RCLL via containers that can be started conveniently using shell functions.
A linux distribution running docker
, docker-compose
, screen
and bash
is required.
clone this repository and source the setup.sh script from the root of the repository:
cd ~/
git clone https://github.com/robocup-logistics/rcll-get-started.git
cd rcll-get-started
source setup.sh
This provides the current terminal with environment variables used for configuration of the software and functions used to orchestrate the software of the RCLL.
Additionally, it also creates a local_setup.sh
file, which you may use to override the provided environment variables. This file is always sourced whenever the setup.sh
is sourced.
To make the commands available per default in all of your terminals, consider sourcing the setup.sh
in your terminal configuration script (e.g., ~/.bashrc
).
- rc_pull: pull all software
- rc_start: start all software as configured, setup a screen session with tabs providing the docker logs
- rc_stop: stop all software
- rc_restart: restart the software
- rc_dump_game_reports: dump game reports from mongodb into an archive
- rc_locate_refbox: shows running refbox instances (useful to check for potential conflicts in network, as only one refbox is supposed to run at a time)
- rc_name_report: rename game reports from the database
- rc_restore_game_reports: restore game reports from a dump
Additionally, individual software pieces may be controlled via commands:
- rc_start_: start the component
- rc_pull_: pull the component
- rc_stop_: stop the component
- rc_enter_: enter a running component with a shell
- rc_exec_: run command inside of the running container of the component
Configuration of the provided software is done via two means: Overriding environment variables and adapting/providing configuration files. The former dictates how containers are setup and started, while the latter are typically then read by the programs to customize them.
To overwrite the defaults which are set in the setup.sh
script, export them in the file local_setup.sh
.
There are environment variables controlling the following things:
- URL and version tag for each container
- Configuration file/directory location
- Which optional containers are started on
rc_start
- To which degree the startup of the refbox is automated
- The arguments passed to the refbox
- MQTT and MongoDB connection information
TODO
Used to just start the refbox and it's frontend without any other tools.
Note that the startup also checks for the existance of a MongoDB on RC_MONGODB_URI
.
Generally it is good to take a look at the refbox wiki, which contains a lot of information.
The refbox requires a running MongoDB instance (any version compatible with the mongocxx-driver of the refbox). Per default, a new MongoDB 5.0 is started on startup. But it is also possible to use an existing instance. Note that the refbox needs to be configured separately to also use the instance.
Env variables for configuration:
-
RC_MONGODB_START
set to true if a mongodb instance should start with the main command, defaults totrue
-
RC_MONGODB_HOST
hostname or ip address where the instance should run on, defaults tolocalhost
-
RC_MONGODB_PORT
port where the intance should run on, defaults to27017
-
RC_MONGODB_URI
Final URI, defaults tomongodb://${RC_MONGODB_HOST}:${RC_MONGODB_PORT}
The refbox logs games into a database, the frontend of the refbox can display that data. In order to do so, a small backend is required that bridges between the database and the frontend.
Env variables for configuration:
-
RC_MONGODB_BACKEND_START
set to true if the mongodb backend should be started with the main command, defaults tofalse
-
RC_MONGODB_BACKEND_DB_NAME
name of the database to use, defaults torcll
, which is the default name of the database the refbox uses.
Note that the backend also utilizes the RC_MONGODB_URI
variable from the mongodb component.
Note: The image is only available via ghcr.io, so you have to login in order to be able to pull it!
Env variables for configuration:
-
RC_MQTT_START
set to true if mqtt bridge should start with the main command -
RC_MQTT_BROKER
broker to connect to -
RC_MQTT_REFBOX
ip of the refbox -
RC_MQTT_TEAM
team name -
RC_MQTT_KEY
crypto key for refbox communication
start the rcll-simulator and the frontend for it. The ui can then be accessed via http://localhost:4200/``.
Env variables for configuration:
-
SIMULATOR_IMAGE
image to use for simulator -
SIMULATOR_TAG
tag to use for simulator -
SIMULATOR_FRONTEND_IMAGE
image to use for simulator frontend -
SIMULATOR_FRONTEND_TAG
tag to use for simulator frontend -
SIMULATOR_CONFIG_FILE
the config file used for the simulator.