Sighthound docker-compose service

Quick start

This repo contains a set of docker-compose services that are meant to be handled using the ./scripts/sh-services script. It is a simple tool that calls docker-compose up/down but the main logic resides in the configuration management. The CLI tool reads the conf folder of every service and performs a merge (using alphanumeric priority) into the .env file that docker-compose uses.

Node devices

If you are on a device that doesn't have sh-device-ui installed, you need to manually:

• Install Sighthound Services
• Install license and key files
• Login to the Docker registry

Installing Sighthound Services

mkdir -p /data/sighthound

Either clone the repo or uncompress latest release.

Option 1: Clone the repo:

# 
git clone git@github.com:sighthoundinc/services.git
cd services
# Optionally: checkout the latest release
RELEASE="v1.3.0"
git checkout tags/${RELEASE}

Option 2: Uncompress latest release:

RELEASE="v1.3.0"
mkdir /data/sighthound/services
cd /data/sighthound/services
wget https://github.com/sighthoundinc/services/releases/download/${RELEASE}/sh-services-${RELEASE}.tar.gz
tar -xvf sh-services-${RELEASE}.tar.gz
rm sh-services-${RELEASE}.tar.gz

Installing SIO analytics license and Docker registry key

Copy (cp) or remote secure copy (scp) the Sighthound provided files to the right location:

# License
mkdir -p /data/sighthound/license
cp ~/Downloads/sighthound-license.json /data/sighthound/license
# Docker key
mkdir -p /data/sighthound/keys
cp ~/Downloads/sighthound-keyfile.json /data/sighthound/keys

Logging in to the docker registry

docker login -u _json_key -p  "`cat /data/sighthound/keys/sighthound-keyfile.json`" us-central1-docker.pkg.dev

Enabling a test RTSP

If you need to test SIO analytics service and don't have an available RTSP source, you can create one by enabling live555 service

./scripts/sh-services enable live555

Then copy the test video file to the live555 mount path:

mkdir -p ./live555/test-data
# cp or scp
cp <my-video>  ./live555/test-data/my-video.mp4

And finally, point SIO to live555:

cp ./sio/examples/live555/* ./sio/conf
# Check the configuration file, verify paramets and save
./scripts/sh-services edit sio

All devices

To start, just run:

./scripts/sh-services up all

and to edit the configuration of services, run:

./scripts/sh-services edit all

Test

Visual test

You can use SIOOutput example to test that SIO Analytics is working, just run:

cd ./examples/SIO_RTSP_Output
docker compose up

And open VLC at rtsp://localhost:8554/live.

Available services

mcp (Media Control Point)

MCP is a service listening for output fron the SIO analytics container, and providing indexing, time-based access and cleanup services for any media generated by it.

Please keep in mind, that keeping MCP configuration mounted volumes, and recordTo/imageSaveDir parameters of the SIO pipleine configuration in sync (i.e. as shipped) is vital to keeping things operational.

If MCP service is disabled and SIO generates media, user MUST provide a cleanup service of their own.

MCP Exposed ports

• 9097 : MCP REST API default port

sio

SIO is the analytics engine processing the live video feed(s), or provided images, and emitting analytics on the AMQP bus. It also optionally persists images and video from the source.

SIO rabbitmq

AMQP broker. If the device operates in a standalone mode, must be enabled. If external AMQP broker is used, SIO and MCP configuration must be adjusted

Exposed ports

• 5672 : RabbitMQ default port
• 15672 : RabbitMQ Management console port

Configuration

First create the data dirs

1. mkdir -p /data/sighthound
2. mkdir -p /data/sighthound/media
3. mkdir -p /data/sighthound/services
4. mkdir -p /data/sighthound/license
5. Install SIO license in /data/sighthound/license/sighthound-license.json
6. Uncompress services tarball into /data/sighthound/services
7. Modify the sio.json file corresponding your sio selected configuration. (Setting the right URL, pipeline parameters...)
8. Finally, create the docker .env files by running: ./scripts/sh-services merge all

SIO pipeline parameters

SIO configuration must be provided in ./sio/conf/sio.json. This configuration file specifies analytics pipeline(s) to be ran, and parameters to be passed to each of those.

Some useful pipeline parameters:

VIDEO_IN: the RTSP URL to use
fpsLimit: limits the fps intake by the analytis pipeline

The following parameters should be kept as is, or set to empty to disable the generation of recorded videeo/images.

recordTo: Path for video storage. Should be: /data/sighthound/media/output/video/${sourceId}/
imageSaveDir: Path for image storage. Should be: /data/sighthound/media/output/image/${sourceId}/

For more advanced options visit VehicleAnalytics Documentation and TrafficAnalytics Documentation

Changing Docker env variables

If you need to modify the .env file of a service, simply create a new .env file like this

echo "SIO_DOCKER_TAG=r221202" >  sio/conf/0009-debug.env

and then update the services:

bash ./scripts/sh-services merge all

Deployment

docker network create sh-device-ui_sh-ui-net || true
bash ./scripts/sh-services up all

At this point you can test your deployment by going to:

http://localhost:15672 and http://localhost:9097

Examples

See development example and demonstration scripts at docs/examples.

Tips and tricks

For using sh-services you may want to run: export PATH=${PATH}:/data/sighthound/services/scripts first.

Then you can do commands like:

sh-services up all

Disabling a service

To disable a service just run:

sh-services disable <service>
# OR
touch <service>/disabled

Re-enabling a service

To enalbe a service just run:

sh-services enable <service>
# OR
rm <service>/disabled