diff --git a/README.md b/README.md index f885890d9f564ffa2e290700e32242e7c4bd5005..487b52daf9dcedeffcdf67604b0dfbf8de4f8c0e 100644 --- a/README.md +++ b/README.md @@ -4,52 +4,73 @@ This repository defines a set of Docker images and Docker compose files that are useful for TANGO control system development. ## Building the Docker images -The Docker images created by this project comprise: +The following Docker images are built by this project: Docker image | Description -----------------------|------------ ska/tango-dependencies | A base image containing TANGO's preferred version of ZeroMQ plus the preferred, patched version of OmniORB. -ska/tango-db | A MariaDB image with TANGO database schema defined. Data is stored separately in a volume +ska/tango-db | A MariaDB image including TANGO database schema. Data is stored separately in a volume. ska/tango-cpp | Core C++ TANGO libraries and applications. ska/tango-java | As per ska/tango-cpp, plus Java applications and bindings -ska/tango-python | Extends ska/tango-cpp, adding pytango Python bindings and itango for interactive TANGO sessions. +ska/tango-python | Extends ska/tango-cpp, adding PyTango Python bindings and itango for interactive TANGO sessions. +ska/tango-pogo | Image for running Pogo and displaying Pogo help. Pogo output can be persisted to a docker volume or to the host machine. +ska/tango-starter | Example image that demonstrates how to package the Starter device in an image. To build the images, from the root of this repository execute: cd docker - make build + make -## Launching a TANGO system -The Docker compose files define a set of containers for a TANGO system. In -addition to the processes to be launched, the files define the connections and -dependencies between containers, plus the order in which they must be started. -A minimal TANGO system consisting of a MariaDB database plus TANGO database -server can be started and stopped with: +## Launching TANGO applications and services +The docker-compose directory contains a set of files that can be used to run a +TANGO system in Docker containers. The following services are defined: +Docker service | Description +----------------|------------ +tangodb | MariaDB database holding TANGO database tables +databaseds | TANGO database device server +tangotest | TANGO test device +jive | Container running Jive application +pogo | Pogo TANGO application +astor | Astor application +starter-example | Example service running TANGO Starter device +itango | interactive itango session + +To start and stop a minimal TANGO system (database and databaseds server), +execute: + + cd docker-compose # start a minimal TANGO system with database and TANGO database server - # Note: omit '-d' if you want the system to launch in the foreground - docker-compose -f tango.yml up -d - # stop the system - docker-compose -f tango.yml down + make up + +Optional applications and device servers can be launched by calling the +_start_ make target followed by the name of the service. For example: + + # still in the docker-compose directory.. + # run Jive + make start jive + # run tangotest + make start tangotest -Additional Docker compose files can be added to the composition to add new -new functions. For instance, to start the TANGO test Java server in addition -to the base system, execute: +Running services can be stopped individually or as a whole using the _stop_ +make target or _down_ make target respectively. For instance, - docker-compose -f tango.yml -f tangotest.yml up -d - + # stop just the tangotest device server, leaving other services running + make stop tangotest + # stop all services and tear down the system + make down -## Interacting with TANGO devices +## Interacting with TANGO applications and devices ### Command line interactions ``itango`` can be used for command line interactions with the system. To make -itango available, add it to the system composition, e.g., +itango available, launch the itango service and attach the terminal to the +itango container. An example session follows: - docker-compose -f tango.yml -f tangotest.yml -f itango.yml up -d + # start a container running itango + make start itango -An example session that attaches the shell to itango and interacts with the -Java test device server follows: - + # attach to the itango container docker attach itango In [1]: dev = DeviceProxy('sys/tg_test/1') @@ -61,16 +82,26 @@ Java test device server follows: To detach from the session without quitting the itango session, press the key combination <CTRL+P><CTRL+Q>. - ### GUI interactions -Graphical applications such as Jive can be launched using docker-compose too. -The Jive container sends X11 traffic to the address defined by the ``MY_IP`` -variable, which must be defined before the system composition is started. -Thereafter, Jive can be launched by adding jive.yml to the system composition, +Graphical applications such as Jive and Pogo can be run in a container, +sending their output to an X11 server running on the host machine. + + # run Jive, using the default IP address determined by the Makefile + make start jive + # run Pogo + make start pogo + +GUI applications send X11 traffic to an IP address determined by the makefile. +This IP address can be overridden by passing a ``DISPLAY`` variable to make, e.g., - export MY_IP=172.16.10.120 - docker-compose -f tango.yml -f tangotest.yml -f jive.yml up -d + # run Jive, sending X11 output to 172.16.10.120:0 + make DISPLAY=172.16.10.120:0 start jive + +Note that the IP address is evaluated inside the Docker container, hence +127.0.0.1 would direct output to the container itself. -The IP address information can be persisted by adding it to the .env file in -this directory. +#### Exporting Pogo output +The Pogo service mounts your home directory as ``/hosthome``. Save Pogo +output to the ``/hosthome`` directory to make it available outside the +container. \ No newline at end of file diff --git a/docker-compose/.env b/docker-compose/.env deleted file mode 100644 index f0a1a512ca4e07f63f69ca7862214534b8d7ae6e..0000000000000000000000000000000000000000 --- a/docker-compose/.env +++ /dev/null @@ -1 +0,0 @@ -MY_IP=172.16.13.28 diff --git a/docker-compose/Makefile b/docker-compose/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..2de2f09209486ab0518b7b797b46f92c9c4e91d7 --- /dev/null +++ b/docker-compose/Makefile @@ -0,0 +1,51 @@ +# Set dir of Makefile to a variable to use later +MAKEPATH := $(abspath $(lastword $(MAKEFILE_LIST))) +BASEDIR := $(notdir $(patsubst %/,%,$(dir $(MAKEPATH)))) + +COMPOSE_FILES := $(wildcard *.yml) +COMPOSE_FILE_ARGS := $(foreach yml,$(COMPOSE_FILES),-f $(yml)) + +# If the first make argument is "start" or "stop"... +ifeq (start,$(firstword $(MAKECMDGOALS))) + SERVICE_TARGET = true +else ifeq (stop,$(firstword $(MAKECMDGOALS))) + SERVICE_TARGET = true +endif +ifdef SERVICE_TARGET + # .. then use the rest as arguments for the make target + SERVICE := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS)) + # ...and turn them into do-nothing targets + $(eval $(SERVICE):;@:) +endif + +# find IP addresses of this machine, setting MY_IP to the first address found +MY_IP := $(shell ifconfig | sed -En 's/127.0.0.1//;s/.*inet (addr:)?(([0-9]*\.){3}[0-9]*).*/\2/p' | head -n1) +DISPLAY = $(MY_IP):0 + +.PHONY: up down minimal start stop status help +.DEFAULT_GOAL := help + +up: minimal ## start the base TANGO system and prepare all services + DISPLAY=$(DISPLAY) docker-compose $(COMPOSE_FILE_ARGS) up --no-start + +down: ## stop all services and tear down the system + DISPLAY=$(DISPLAY) docker-compose $(COMPOSE_FILE_ARGS) down + +minimal: ## start the base TANGO system + docker-compose -f tango.yml up -d + +start: up ## start a service (usage: make start <servicename>) + DISPLAY=$(DISPLAY) docker-compose $(COMPOSE_FILE_ARGS) start $(SERVICE) + +stop: ## stop a service (usage: make stop <servicename>) + DISPLAY=$(DISPLAY) docker-compose $(COMPOSE_FILE_ARGS) stop $(SERVICE) + +status: ## show the container status + DISPLAY=$(DISPLAY) docker-compose $(COMPOSE_FILE_ARGS) ps + +clean: down ## clear all TANGO database entries + docker volume rm $(BASEDIR)_tangodb + +help: ## show this help. + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' + diff --git a/docker-compose/astor.yml b/docker-compose/astor.yml index 8a70d56fde76d6c18511cc0dddd1c9851f7ffe71..0b9a2fe7be69664f980457c6eea6ef097cf9f201 100644 --- a/docker-compose/astor.yml +++ b/docker-compose/astor.yml @@ -23,7 +23,7 @@ services: - $HOME:/hosthome:ro environment: - XAUTHORITY=/hosthome/.Xauthority - - DISPLAY=${MY_IP}:0 + - DISPLAY=${DISPLAY} - TANGO_HOST=databaseds:10000 entrypoint: - /usr/local/bin/wait-for-it.sh diff --git a/docker-compose/jive.yml b/docker-compose/jive.yml index 5d6f4789c21a8f7572b74278f47c0a184cb3b1a5..0c65daa9cce782d09f770c054fc69aeaf48edd0a 100644 --- a/docker-compose/jive.yml +++ b/docker-compose/jive.yml @@ -22,7 +22,7 @@ services: - $HOME:/hosthome:ro environment: - XAUTHORITY=/hosthome/.Xauthority - - DISPLAY=${MY_IP}:0 + - DISPLAY=${DISPLAY} - TANGO_HOST=databaseds:10000 entrypoint: - /usr/local/bin/wait-for-it.sh diff --git a/docker-compose/pogo.yml b/docker-compose/pogo.yml index bb8f3de7b6f0cdd7091c2e475a20d37960316ee0..0ff955c586a6716f035f720ddc71e8ff18edf88c 100644 --- a/docker-compose/pogo.yml +++ b/docker-compose/pogo.yml @@ -29,4 +29,4 @@ services: - $HOME:/hosthome:rw environment: - XAUTHORITY=/hosthome/.Xauthority - - DISPLAY=${MY_IP}:0 + - DISPLAY=${DISPLAY}