Sequencer

Overview

The ‘Sequencer’ is a tool with a graphical front end that can be used to run OCS Clients. Often this will be done with the help of another library, enabling the command of many Clients in sequence. This page describes the configuration and use of the Sequencer.

Description

The Sequencer tool is called nextline. Nextline is composed of a backend API, which uses GraphQL, and a graphical frontend written in VueJS. The graphical front end is accessible in your web browser and provides an interface for running Python code. The code is passed to and executed on the backend.

Typically these components will run in two separate Docker containers. In practice you will have these both behind a reverse proxy. This proxy server may be in another container. For the purposes of this page we will use an nginx proxy in a separate container (similar to the one described in Web Server Setup.)

In order to orchestrate many OCS Clients, we use a helper library called sorunlib. For setup of nextline with sorunlib we provide a pre-build Docker image called the so-daq-sequencer.

Setup

Here we setup an example set of Docker containers which make nextline available on your localhost. Here is an example docker-compose.yml file that provides both nextline components, an nginx reverse proxy, and persistent storage for the backend database:

version: '3.7'

networks:
  default:
    external:
      name: ocs-net

services:
  frontend:
    image: ghcr.io/simonsobs/nextline-web:latest
    container_name: nextline-web
    environment:
      - API_HTTP=http://localhost/nextline/api/
      - PUBLIC_PATH=/nextline/

  backend:
    image: ghcr.io/simonsobs/so-daq-sequencer:latest
    container_name: nextline-backend
    environment:
      - NEXTLINE_DB__URL=sqlite:////db/db.sqlite3
      - OCS_CONFIG_DIR=/config
    volumes:
      - /srv/sequencer/db:/db
      - ${OCS_CONFIG_DIR}:/config:ro

  nginx:
    image: nginx:latest
    restart: always
    volumes:
     - ./nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
     - "127.0.0.1:80:80"

Note

This example makes use of the externally defined network “ocs-net”. This is to allow the backend to connect to the crossbar server. Your needs may differ depending on your network configuration. For details on an “ocs-net” like configuration see the OCS Docs.

Note

Your site-config-file must point to the crossbar address as if from the container running the so-daq-sequencer by default, otherwise the sequencer will be unable to connect. We are working on solution/recommended configuration upstream in OCS. Until that is solved be aware that this may limit local commanding via other methods like running control programs on the commandline.

Web Server Setup has a full example of nginx.conf. What we need to add to that config is:

http {
  # Nextline Websocket Connection
  # For websocket connection upgrade
  # https://www.nginx.com/blog/websocket-nginx/
  map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
  }

  server {
      ...

    location /nextline/ {
      proxy_pass http://nextline-web/nextline/;

      #auth_basic "Restricted Content";
      #auth_basic_user_file /etc/nginx/.htpasswd;
    }

    location /nextline/api/ {
      proxy_pass http://nextline-backend:8000/;

      # https://www.nginx.com/blog/websocket-nginx/
      proxy_http_version 1.1;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection $connection_upgrade;
      proxy_set_header Host $host;

      #auth_basic "Restricted Content";
      #auth_basic_user_file /etc/nginx/.htpasswd;
    }
  }
}

Warning

You absolutely must put the Sequencer behind some form on authentication. The entire point of the tool is remote code execution, making it dangerous if exposed to the open internet.

Once you bring these containers up (with docker-compose up -d), you should be able to access the Sequencer by pointing your web browser to http://localhost/nextline/.

Note

This configuration will get you a standalone local nextline behind a proxy. To run nextline on a public facing URL you need to set API_HTTP appropriately. For example:

- API_HTTP=https://example.com/nextline/api/