Quickstart

We will assume you have already gone through the Installation part of the documentation and thus have installed the required dependencies, namely Docker, Docker Compose, and ocs.

In this example we will run an OCS Agent (the Fake Data Agent) which generates random data, pass the data to an InfluxDB, and view the data in Grafana.

Configuration Files

Before we begin we need to setup the configuration files. Let’s first create a directory to keep all of our site configuration files in:

$ mkdir -p ocs-site-configs
$ cd ocs-site-configs/

OCS needs to know where these configuration files are stored, and does so through the OCS_CONFIG_DIR environment variable. In the terminal you are using run:

$ export OCS_CONFIG_DIR=$(pwd)

You can also set this more permanently in your .bashrc file. More details in Environment Setup.

Note

This quickstart example includes only a couple Agents. The Agent Reference pages, linked in the sidebar, contain example configuration blocks for configuring each Agent.

Next, we need to write our two configuration files, starting with the OCS site config file. You must replace “<hostname>” in this file with the hostname of the computer you are working on. Also replace “<user>” with your username, or change the paths “<user>” is in entirely to reflect your desired file structure.

default.yaml:

# Site configuration for a fake observatory.
hub:

  wamp_server: ws://localhost:8001/ws
  wamp_http: http://localhost:8001/call
  wamp_realm: test_realm
  address_root: observatory

hosts:

  <hostname>: {
    # Directory for logs.
    'log-dir': '/home/<user>/log/ocs/',

    # List of additional paths to Agent plugin modules.
    'agent-paths': [
        '/home/<user>/git/ocs/agents/',
        '/home/<user>/git/socs/agents/',
    ],

    # Agents running directly on the host machine
    # Note: We aren't going to run this Agent in the quickstart example,
    #       but this gives a good example of configuring an agent directly
    #       on the host
    'agent-instances': [
      {'agent-class': 'HostManager',
       'instance-id': 'hm-1'},
    ]
  }

  <hostname>-docker: {
    # Address of crossbar within Docker (based on service name)
    'wamp_server': 'ws://crossbar:8001/ws',
    'wamp_http': 'http://crossbar:8001/call',

    # Agents running within Docker containers
    'agent-instances': [
      {'agent-class': 'InfluxDBAgent',
       'instance-id': 'influxagent',
       'arguments': ['--initial-state', 'record']},
      {'agent-class': 'FakeDataAgent',
       'instance-id': 'fake-data1',
       'arguments': ['--mode', 'acq',
                     '--num-channels', '16',
                     '--sample-rate', '4']},
    ]
  }

Next, we need to define the Docker Compose file. Again, “<hostname>” should be replaced with the hostname of your computer.

docker-compose.yaml:

version: '3.7'
volumes:
  grafana-storage:
  influxdb-storage:

services:
  # --------------------------------------------------------------------------
  # Grafana for the live monitor.
  # --------------------------------------------------------------------------
  grafana:
    image: grafana/grafana:latest
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - grafana-storage:/var/lib/grafana

  # InfluxDB Backend for Grafana
  influxdb:
    image: influxdb:1.7
    container_name: "influxdb"
    restart: always
    ports:
      - "8086:8086"
    environment:
      - INFLUXDB_HTTP_LOG_ENABLED=false
    volumes:
      - influxdb-storage:/var/lib/influxdb

  # --------------------------------------------------------------------------
  # Crossbar Server
  # --------------------------------------------------------------------------
  crossbar:
    image: simonsobs/ocs-crossbar:latest
    ports:
      - "127.0.0.1:8001:8001" # expose for OCS
    environment:
         - PYTHONUNBUFFERED=1

  # --------------------------------------------------------------------------
  # OCS Components
  # --------------------------------------------------------------------------
  # Fake Data Agent for example housekeeping data
  ocs-fake-data1:
    image: simonsobs/ocs:latest
    hostname: <hostname>-docker
    environment:
      - INSTANCE_ID=fake-data1
      - LOGLEVEL=info
    volumes:
      - ${OCS_CONFIG_DIR}:/config:ro

  # InfluxDB Publisher
  ocs-influx-publisher:
    image: simonsobs/ocs:latest
    hostname: <hostname>-docker
    environment:
      - INSTANCE_ID=influxagent
    volumes:
      - ${OCS_CONFIG_DIR}:/config:ro

Running

Now that the system is configured, we can start it with a single docker compose command:

$ sudo -E docker compose up -d
Creating network "ocs-site-configs_default" with the default driver
Creating ocs-site-configs_ocs-influx-publisher_1 ... done
Creating ocs-site-configs_grafana_1              ... done
Creating ocs-site-configs_ocs-fake-data1_1       ... done
Creating ocs-site-configs_crossbar_1             ... done
Creating influxdb                                ... done

Note

If this is the first time you have run the example, you will see Docker Compose “pulling” (downloading) all the required images from DockerHub.

Note

The -E here preserves the user environment within sudo, so $OCS_CONFIG_DIR still resolves properly.

You can view the running containers with:

$ sudo docker ps
CONTAINER ID   IMAGE                                           COMMAND                  CREATED          STATUS          PORTS                                          NAMES
dc3792e8d4f3   influxdb:1.7                                    "/entrypoint.sh infl…"   27 seconds ago   Up 25 seconds   0.0.0.0:8086->8086/tcp, :::8086->8086/tcp      influxdb
7aa0c07345de   simonsobs/ocs-crossbar:latest                   "crossbar start --cb…"   27 seconds ago   Up 25 seconds   8000/tcp, 8080/tcp, 127.0.0.1:8001->8001/tcp   ocs-site-configs_crossbar_1
88dd47cc6714   simonsobs/ocs:latest                            "dumb-init python3 -…"   27 seconds ago   Up 25 seconds                                                  ocs-site-configs_ocs-fake-data1_1
41231a482dec   simonsobs/ocs:latest                            "dumb-init python3 -…"   27 seconds ago   Up 25 seconds                                                  ocs-site-configs_ocs-influx-publisher_1
bcdc0423ab4c   grafana/grafana:latest                          "/run.sh"                27 seconds ago   Up 25 seconds   127.0.0.1:3000->3000/tcp                       ocs-site-configs_grafana_1

If anything has gone wrong and some containers have not started, you can view all containers, even stopped ones with:

$ sudo docker container ls -a

Commanding

The Agents can now be commanded using an OCS Client. To do so, we will open a Python interpreter and run:

$ python
>>> from ocs.ocs_client import OCSClient
>>> client = OCSClient('fake-data1')
>>> client.delay_task.start(delay=10)

For more details on how to use OCSClient and how to write a control program see the Developer Guide section on Clients and Control Programs.

Viewing

Now that all of the containers are running we can view the random data being automatically generated by the Fake Data Agent in Grafana. You can access Grafana by pointing your web browswer to http://localhost:3000/. For information about how to configure the InfluxDB data source please see InfluxDB Publisher Agent. Following that page you should be able to view a live datastream from the Fake Data Agent.

Note

The default Grafana credentials are “admin”/”admin”.

Next Steps

From here the possibilities are endless. You can add additional Agents for more hardware, viewing their datastreams in Grafana, write a Client to interact with the running Agents, or develop your own Agent to control any unsupported hardware.

Shutdown

If you’d just like to shutdown the example you can run:

$ sudo docker compose down

This will shutdown and remove all the containers.

If you would also like to remove any Docker images you may have downloaded you can identify them with:

$ sudo docker image ls

And remove them with:

$ sudo docker image rm <image name>

Warning

Running the following command will cause data within the containers to be lost! This includes Grafana dashboard configurations and data within InfluxDB.

If you would like to totally remove all trace of your OCS instance, including the storage volumes, run:

$ sudo docker compose down --volumes