Skip to content
Snippets Groups Projects
Commit aa9b0910 authored by Stewart Williams's avatar Stewart Williams
Browse files

Update to latest ska-skeleton docs

parent 814b861f
No related branches found
No related tags found
No related merge requests found
# TANGO Docker containers # TANGO Docker containers
This repository defines a set of Docker images and Docker compose files that This project defines a set of Docker images and Docker compose files
are useful for TANGO control system development. that are useful for TANGO control system development.
## Building the Docker images See the documentation in the ``docs`` folder for build and usage
The following Docker images are built by this project: instructions.
Docker image | Description
-------------------|------------
tango-dependencies | A base image containing TANGO's preferred version of ZeroMQ plus the preferred, patched version of OmniORB.
tango-db | A MariaDB image including TANGO database schema. Data is stored separately in a volume.
tango-cpp | Core C++ TANGO libraries and applications.
tango-java | As per ska/tango-cpp, plus Java applications and bindings
tango-python | Extends ska/tango-cpp, adding PyTango Python bindings and itango for interactive TANGO sessions.
tango-pogo | Image for running Pogo and displaying Pogo help. Pogo output can be persisted to a docker volume or to the host machine.
tango-starter | Example image that demonstrates how to package the Starter device in an image.
To build and register the images locally, from the root of this repository
execute:
cd docker
# build and register TBC/tango-cpp, TBC/tango-jive, etc. locally
make build
Optionally, you can register images to an alternative Docker registry account
by supplying the ``DOCKER_REGISTRY_HOST`` and ``DOCKER_REGISTRY_USER``
Makefile variables, e.g.,
# build and register images as foo/tango-cpp, foo/tango-jive, etc.
make DOCKER_REGISTRY_USER=foo build
Push the built images to a Docker registry using ``make push`` target. The
URL of the registry can be specified by providing the ``DOCKER_REGISTRY_HOST``
Makefile argument.
# push the images to the Docker registry, making them publicly
# available as foo/tango-cpp, foo/tango-jive, etc.
make DOCKER_REGISTRY_USER=foo DOCKER_REGISTRY_HOST=docker.io push
## 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
logviewer | Container running TANGO log viewer
pogo | Pogo TANGO application
astor | Astor application
starter-example | Example service running TANGO Starter device
itango | interactive itango session
To pull pre-built images from the Docker hub, execute:
cd docker-compose
# download official SKA images
make pull
Optional: the images can be pulled from an alternative account by supplying
the DOCKER_REGISTRY_USER Makefile variable, e.g.,
cd docker-compose
# download foo/tango-cpp, foo/tango-jive, etc.
make DOCKER_REGISTRY_USER=foo pull
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
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
Running services can be stopped individually or as a whole using the _stop_
make target or _down_ make target respectively. For instance,
# 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 applications and devices
### Command line interactions
``itango`` can be used for command line interactions with the system. To make
itango available, launch the itango service and attach the terminal to the
itango container. An example session follows:
# start the tangotest device, which we'll connect to using itango
make start tangotest
# start the itango container
make start itango
# attach to the itango container
docker attach itango
In [1]: dev = DeviceProxy('sys/tg_test/1')
In [2]: dev.string_scalar
Out[2]: 'Default string'
...
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 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.,
# 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.
#### 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
...@@ -5,7 +5,7 @@ ...@@ -5,7 +5,7 @@
SPHINXOPTS = SPHINXOPTS =
SPHINXBUILD = python -msphinx SPHINXBUILD = python -msphinx
SPHINXPROJ = skeleton SPHINXPROJ = skeleton
SOURCEDIR = source SOURCEDIR = src
BUILDDIR = build BUILDDIR = build
# Put it first so that "make" without argument is like "make help". # Put it first so that "make" without argument is like "make help".
......
File moved
File moved
File moved
...@@ -53,9 +53,9 @@ source_suffix = '.rst' ...@@ -53,9 +53,9 @@ source_suffix = '.rst'
master_doc = 'index' master_doc = 'index'
# General information about the project. # General information about the project.
project = 'Skeleton project' project = 'SKA Docker Images'
copyright = '2018, Marco Bartolini' copyright = '2018, Stewart Williams'
author = 'Marco Bartolini' author = 'Stewart Williams'
# The version info for the project you're documenting, acts as replacement for # The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the # |version| and |release|, also used in various other places throughout the
...@@ -102,11 +102,10 @@ html_context = { ...@@ -102,11 +102,10 @@ html_context = {
'logo': 'img/logo.jpg', 'logo': 'img/logo.jpg',
'theme_logo_only': True, 'theme_logo_only': True,
'display_github': True, # Integrate GitHub 'display_github': True, # Integrate GitHub
'github_user': 'flyingfrog81', # Username 'github_user': 'ska-telescope', # Username
'github_repo': 'ska-skeleton', # Repo name 'github_repo': 'docker', # Repo name
'github_version': 'master', # Version 'github_version': 'master', # Version
'conf_py_path': '/docs/src/', # Path in the checkout to the docs root 'conf_py_path': '/docs/src/', # Path in the checkout to the docs root
} }
# Add any paths that contain custom static files (such as style sheets) here, # Add any paths that contain custom static files (such as style sheets) here,
...@@ -171,7 +170,7 @@ latex_documents = [ ...@@ -171,7 +170,7 @@ latex_documents = [
# (source start file, name, description, authors, manual section). # (source start file, name, description, authors, manual section).
man_pages = [ man_pages = [
(master_doc, '{{project-name}}', '{{project-name}} Documentation', (master_doc, '{{project-name}}', '{{project-name}} Documentation',
[{{author}}], 1) ['{{author}}'], 1)
] ]
...@@ -182,7 +181,7 @@ man_pages = [ ...@@ -182,7 +181,7 @@ man_pages = [
# dir menu entry, description, category) # dir menu entry, description, category)
texinfo_documents = [ texinfo_documents = [
(master_doc, '{{project-name}}', '{{project-name}} Documentation', (master_doc, '{{project-name}}', '{{project-name}} Documentation',
{{author}}, '{{project-name}}', 'One line description of project.', '{{author}}', '{{project-name}}', 'One line description of project.',
'Miscellaneous'), 'Miscellaneous'),
] ]
......
Launching TANGO applications and services in containers
=======================================================
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 |
+-----------------+------------------------------------------------+
| logviewer | Container running TANGO log viewer |
+-----------------+------------------------------------------------+
| pogo | Pogo TANGO application |
+-----------------+------------------------------------------------+
| astor | Astor application |
+-----------------+------------------------------------------------+
| starter-example | Example service running TANGO Starter device |
+-----------------+------------------------------------------------+
| itango | interactive itango session |
+-----------------+------------------------------------------------+
To pull pre-built images from the Docker hub, execute:
.. code-block:: console
cd docker-compose
# download official SKA images
make pull
Optional: the images can be pulled from an alternative account by
supplying the DOCKER_REGISTRY_USER Makefile variable, e.g.,
.. code-block:: console
cd docker-compose
# download foo/tango-cpp, foo/tango-jive, etc.
make DOCKER_REGISTRY_USER=foo pull
To start and stop a minimal TANGO system (database and databaseds
server), execute:
.. code-block:: console
cd docker-compose
# start a minimal TANGO system with database and TANGO database server
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:
.. code-block:: console
# still in the docker-compose directory..
# run Jive
make start jive
# run tangotest
make start tangotest
Running services can be stopped individually or as a whole using the
*stop* make target or *down* make target respectively. For instance,
.. code-block:: console
# stop just the tangotest device server, leaving other services running
make stop tangotest
# stop all services and tear down the system
make down
Building the Docker images
==========================
The following Docker images are built by this project:
+--------------------+-------------------------------------------------------+
| Docker image | Description |
+====================+=======================================================+
| tango-dependencies | A base image containing TANGO's preferred version of |
| | ZeroMQ plus the preferred, patched version of |
| | OmniORB. |
+--------------------+-------------------------------------------------------+
| tango-db | A MariaDB image including TANGO database schema. Data |
| | is stored separately in a volume. |
+--------------------+-------------------------------------------------------+
| tango-cpp | Core C++ TANGO libraries and applications. |
+--------------------+-------------------------------------------------------+
| tango-pogo | Image for running Pogo and displaying Pogo help. Pogo |
| | output can be persisted to a docker volume or to the |
| | host machine. |
+--------------------+-------------------------------------------------------+
| tango-java | As per ska/tango-cpp, plus Java applications and |
| | bindings |
+--------------------+-------------------------------------------------------+
| tango-python | Extends ska/tango-cpp, adding PyTango Python bindings |
| | and itango for interactive TANGO sessions. |
+--------------------+-------------------------------------------------------+
| tango-starter | Example image that demonstrates how to package the |
| | Starter device in an image. |
+--------------------+-------------------------------------------------------+
To build and register the images locally, from the root of this
repository execute:
.. code-block:: console
cd docker
# build and register TBC/tango-cpp, TBC/tango-jive, etc. locally
make build
Optionally, you can register images to an alternative Docker registry
account by supplying the ``DOCKER_REGISTRY_HOST`` and
``DOCKER_REGISTRY_USER`` Makefile variables, e.g.,
.. code-block:: console
# build and register images as foo/tango-cpp, foo/tango-jive, etc.
make DOCKER_REGISTRY_USER=foo build
Pushing the images to a Docker registry
---------------------------------------
Push the built images to a Docker registry using ``make push`` target.
The URL of the registry can be specified by providing the
``DOCKER_REGISTRY_HOST`` Makefile argument.
.. code-block:: console
# push the images to the Docker registry, making them publicly
# available as foo/tango-cpp, foo/tango-jive, etc.
make DOCKER_REGISTRY_USER=foo DOCKER_REGISTRY_HOST=docker.io push
...@@ -3,14 +3,19 @@ ...@@ -3,14 +3,19 @@
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. contain the root `toctree` directive.
Skeleton Project SKA Docker Images
================ =================
This project defines a set of Docker images and Docker compose files
that are useful for TANGO control system development.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:caption: Contents: :caption: Contents:
docker_images
docker_compose
interactions
Indices and tables Indices and tables
================== ==================
......
Interacting with TANGO applications and devices
===============================================
Command line interactions
-------------------------
``itango`` can be used for command line interactions with the system. To
make itango available, launch the itango service and attach the terminal
to the itango container. An example session follows:
::
# start the tangotest device, which we'll connect to using itango
make start tangotest
# start the itango container
make start itango
# attach to the itango container
docker attach itango
In [1]: dev = DeviceProxy('sys/tg_test/1')
In [2]: dev.string_scalar
Out[2]: 'Default string'
...
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 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.,
::
# 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.
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
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment