Docker

OCS Agents are commonly deployed in Docker containers. OCS provides a base Docker image, which contains the dependencies required to run OCS and all of the core agents. This page describes the details of this image, and how to build upon it to deploy your Agent(s) or OCS plugin.

OCS Base Image

The OCS base image is built from the Dockerfile in the root of the respository, shown here:

# ocs-docker
# A container setup with an installation of ocs.

# Use ubuntu base image
FROM simonsobs/so3g:v0.1.3-13-g5471f0d

# Set locale
ENV LANG C.UTF-8

# Create ocs user and group
RUN groupadd -g 9000 ocs && \
    useradd -m -l -u 9000 -g 9000 ocs

# aggregator: Prepare data directory for mount
RUN mkdir -p /data && \
    chown ocs:ocs /data

# Setup configuration environment
ENV OCS_CONFIG_DIR=/config

# Disable output buffer
ENV PYTHONUNBUFFERED=1

# Install python and pip
RUN apt-get update && apt-get install -y python3 \
    python3-pip \
    vim

# Install init system
RUN pip3 install dumb-init

# Copy in and install requirements
# This will leverage the cache for rebuilds when modifying OCS, avoiding
# downloading all the requirements again
COPY requirements/ /app/ocs/requirements
COPY requirements.txt /app/ocs/requirements.txt
WORKDIR /app/ocs/
RUN pip3 install -r requirements.txt

# Copy the current directory contents into the container at /app
COPY . /app/ocs/

# Install ocs
RUN pip3 install .

# Reset workdir to avoid local imports
WORKDIR /

# Run agent on container startup
ENTRYPOINT ["dumb-init", "ocs-agent-cli"]

This file describes the steps taken to build the base image. This includes configuring an ocs user, creating a directory to store data from the aggregator, setting up the configuration file directory, installing dependencies, installing ocs, and setting the default entrypoint to launch an OCS Agent via ocs-agent-cli. See the Dockerfile reference in the Docker documentation for more information about how to write a Dockerfile.

Building Upon the Base Image

When writing an OCS Agent (or plugin) you can build upon this OCS base image to deploy your Agent (or plugin). To do so you would write a new Dockerfile that looks something like:

# my-ocs-agent-docker
# A brief description of your image.

# Use the ocs image as a base
FROM simonsobs/ocs:latest

# Install required dependencies
RUN apt-get update && apt-get install -y rsync \
    wget \
    python3-pip

# Copy in and install requirements
COPY requirements.txt /app/my-ocs-agent/requirements.txt
WORKDIR /app/my-ocs-agent/
RUN pip3 install -r requirements.txt

# Copy the current directory contents into the container at /app
COPY . /app/my-ocs-agent/

# Install my-ocs-agent
RUN pip3 install .

# Run agent on container startup
ENTRYPOINT ["dumb-init", "ocs-agent-cli"]

This assumes you have a requirements.txt file for any additional dependencies for your Agent, and that you have a package to install, like an OCS plugin.

Note

Properities of the parent image are inherited, for example OCS_CONFIG_DIR will still be configured as it was in the OCS base image unless otherwise changed in your Dockerfile.

This image now includes all the dependencies you need to run your Agent and you can move on to using the image. This is commonly done with Docker Compose, as described in the following section.

Using An OCS Image

Whether you are using the OCS base image to run a core agent or using an image you have made to extend the functionality of OCS with your own Agent or plugin you can configure the image to run using Docker Compose. For example, using the base image to run a core agent would look something like:

ocs-agent:
    image: simonsobs/ocs:latest
    hostname: ocs-docker
    volumes:
      - ${OCS_CONFIG_DIR}:/config:ro
    environment:
      - INSTANCE_ID=registry

Environment variables used to configure the Agent are listed in the following table:

Docker Environment Variables
Variable	CLI Equivalent	Description
`INSTANCE_ID`	`--instance-id`	Agent instance-id, e.g. `aggregator`
`SITE_HOST`	`--site-host`	Hostname to use when looking up the instance configuration in the Site Config File, e.g. `host1`.
`SITE_HUB`	`--site-hub`	WAMP server address, e.g. `ws://10.10.10.10:8001/ws`
`SITE_HTTP`	`--site-http`	WAMP server HTTP address, e.g. `http://10.10.10.10:8001/call`

Any additional flags needed can be added using command. This includes if you need to run a one-off Agent that is not apart of an OCS plugin. This would add the following lines to your docker-compose.yaml service configuration:

command:
  - '--agent /app/my-ocs-agent/agent.py --entrypoint main'

Note

Arguments passed on the commandline (or in the command block of your configuration) take precedent over any settings set via environment variables.

For more specific examples on how to use each Agent, see the Agent’s reference page in the sidebar.