Merge pull request #142 from strykeforce/docker-instructions

Added instructions to run Deadeye in Docker

Author: jhh

README.md

@@ -1,24 +1,33 @@
 # Deadeye
 
 **Deadeye** is a vision system for FIRST<sup>®</sup> Robotics Competition
-robots designed to be run on a vision coprocessor, such as the [Jetson Nano
-Developer Kit][jndk]. It consists of several parts:
+robots designed to be run on a vision coprocessor, such as a Linux single-board
+computer. It has been actively used with the [Jetson Nano Developer Kit][jndk]
+and [Orange Pi 5 Plus][orangepi]. It consists of several parts:
 
 [jndk]: https://developer.nvidia.com/EMBEDDED/jetson-nano-developer-kit/
+[orangepi]: http://www.orangepi.org/index.html
 
 - Vision Daemon - C++ vision capture and processing pipeline.
 - Client Library - Java library for use with FRC robots and other clients
 - Admin Web UI - React web interface to manage Deadeye vision system.
 - Admin Server and Tools - Python web service to connect admin web UI to vision
   daemon backend.
-- Provisioning Tools - Ansible playbooks for provisioning and deploying the
-  system to vision coprocessors.
+- Deployment Tools - Ansible playbooks for provisioning and deploying the
+  system to vision coprocessors. **This method of deployment is deprecated in favor of using Docker (see below).**
 
 ## Documentation
 
-- [Installation and usage instructions](https://strykeforce.github.io/deadeye/)
+- [Installation and usage instructions](https://strykeforce.github.io/deadeye/) - these instructions are deprecated in favor of using Docker (see below).
 - The Java client library [javadocs](https://strykeforce.github.io/deadeye/javadoc/)
 
+## Docker Installation and Usage
+
+This is the preferred method of deploying and operating the Deadeye system.
+Docker is readily available on most, if not all, Linux distributions used on
+vision coproccessors. See the [installation and usage instructions](./docker/)
+in the docker subdirectory of this repo.
+
 ## Contributing
 
 Deadeye is free and open source. You can find the source code on

docker/README.md

@@ -0,0 +1,99 @@
+# Docker Installation and Usage
+
+This is the preferred method of deploying and operating the Deadeye system.
+Docker is readily available on most, if not all, Linux distributions used on
+vision coproccessors.
+
+## Installation
+
+We'll use the [Docker Compose](https://docs.docker.com/compose/) tool to deploy
+and operate Deadeye. The example commands below work on an Orange Pi running
+their Ubuntu based [Orange Pi OS
+(OH)](http://www.orangepi.org/html/softWare/orangePiOS/oh.html).
+
+```sh
+sudo apt update
+sudo apt install docker-compose-plugin
+```
+
+### Docker Compose
+
+Edit the `docker-compose.yaml` file as appropriate for your system. Select the
+[docker image tags](https://hub.docker.com/search?q=j3ff/deadeye) to use and
+edit the lines containing:
+
+```yaml
+daemon:
+  image: j3ff/deadeye-daemon:<TAG>
+admin:
+  image: j3ff/deadeye-admin:<TAG>
+web:
+  image: j3ff/deadeye-web:<TAG>
+```
+
+There are a number of environment variables beginning with `DEADEYE_` that you
+may need to edit.
+
+### systemd
+
+The Deadeye containers are run using systemd instead of normal container restart
+policies to work around Docker issues with camera device names.
+
+Edit and install the `deadeye.service` systemd service definition as appropriate
+for your system, for example:
+
+```
+Environment="DOCKER_COMPOSE_FILE=/home/orangepi/deadeye/docker-compose.yml"
+Environment="CAMERA_PATH=/dev/v4l/by-id/usb-Microsoft_Microsoft®_LifeCam_HD-3000-video-index0"
+```
+
+Install in `/etc/systemd/system/deadeye.service` and reload systemd services:
+
+```sh
+systemctl daemon-reload
+```
+
+## Operation
+
+Start the Deadeye containers with:
+
+```sh
+sudo systemctl start deadeye
+```
+
+Stop the Deadeye containers with:
+
+```sh
+sudo systemctl stop deadeye
+```
+
+View container logs:
+
+```sh
+# in directory containing docker-compose.yaml
+docker compose logs -f
+
+# or alternatively, where SERVICE is one of: admin, daemon, web
+docker compose logs $SERVICE
+```
+
+Updating the containers to a new version:
+
+```sh
+sudo systemctl stop deadeye
+
+# in directory containing docker-compose.yaml
+# edit the docker image tag(s) in docker-compose.yaml
+docker compose pull
+
+# it's a good idea to recreate the docker network
+docker compose down
+
+sudo systemctl start deadeye
+```
+
+Clean up old docker images and containers.
+
+```sh
+docker system prune
+```

docker/deadeye.service

@@ -6,13 +6,18 @@ Requires=docker.service
 [Service]
 Type=oneshot
 RemainAfterExit=yes
+
+Environment="DOCKER_COMPOSE_FILE=/home/orangepi/deadeye/docker-compose.yml"
+Environment="CAMERA_PATH=/dev/v4l/by-id/usb-Microsoft_Microsoft®_LifeCam_HD-3000-video-index0"
+
 ExecStart=/bin/bash -c '\
-  CAMERA_DEV=$(readlink --canonicalize --no-newline /dev/v4l/by-id/usb-Microsoft_Microsoft®_LifeCam_HD-3000-video-index0) \
-  docker compose -f /home/orangepi/deadeye/docker-compose.yml up --detach \
+  CAMERA_DEV=$(readlink --canonicalize --no-newline ${CAMERA_PATH}) \
+  docker compose -f "${DOCKER_COMPOSE_FILE}" up --detach \
   '
+
 ExecStop=/bin/bash -c '\
-  CAMERA_DEV=$(readlink --canonicalize --no-newline /dev/v4l/by-id/usb-Microsoft_Microsoft®_LifeCam_HD-3000-video-index0) \
-  docker compose -f /home/orangepi/deadeye/docker-compose.yml stop \
+  CAMERA_DEV=$(readlink --canonicalize --no-newline ${CAMERA_PATH}) \
+  docker compose -f "${DOCKER_COMPOSE_FILE}" stop \
   '
 
 [Install]