Merge 04fc317 into f6b3925

simonsobs · Oct 29, 2020 · 16dfe8c · 16dfe8c
2 parents f6b3925 + 04fc317
commit 16dfe8c
Show file tree

Hide file tree

Showing 10 changed files with 281 additions and 52 deletions.
diff --git a/README.rst b/README.rst
@@ -6,8 +6,8 @@ OCS - Observatory Control System
     :target: https://github.com/simonsobs/ocs/actions?query=workflow%3A%22Build+Develop+Images%22
     :alt: GitHub Workflow Status
 
-.. image:: https://readthedocs.org/projects/ocs/badge/?version=latest
-    :target: https://ocs.readthedocs.io/en/latest/?badge=latest
+.. image:: https://readthedocs.org/projects/ocs/badge/?version=develop
+    :target: https://ocs.readthedocs.io/en/develop/?badge=develop
     :alt: Documentation Status
 .. image:: https://coveralls.io/repos/github/simonsobs/ocs/badge.svg
     :target: https://coveralls.io/github/simonsobs/ocs

diff --git a/docker/crossbar/Dockerfile b/docker/crossbar/Dockerfile
@@ -1,24 +1,23 @@
 # ocs-crossbar
 # A containerized crossbar server.
+# https://crossbar.io/docs/Creating-Docker-Images/
 
 # Use ocs base image
-FROM ocs:latest
+FROM crossbario/crossbar:cpy3-20.8.1
 
-# Set the working directory to /app/crossbar
-WORKDIR /app/crossbar
+# Run as root to put config in place and chown
+USER root
 
 # Copy in config and requirements files
-COPY . /app/crossbar/
+COPY config.json /ocs/.crossbar/config.json
+RUN chown -R crossbar:crossbar /ocs
 
-# Required for crossbar build to work
-RUN apt-get update && apt-get install -y libsnappy-dev
-
-# Install requirements
-RUN pip3 install -r requirements.txt
+# Run image as crossbar user during normal operation
+USER crossbar
 
 # Default OCS crossbar port
 EXPOSE 8001
 
 # Run crossbar when the container launches
-# User made config.json should be mounted to /app/crossbar/config.json
-CMD ["crossbar", "start"]
+# User made config.json should be mounted to /ocs/.crossbar/config.json
+ENTRYPOINT ["crossbar", "start", "--cbdir", "/ocs/.crossbar"]
diff --git a/docker/crossbar/config.json b/docker/crossbar/config.json
@@ -70,7 +70,14 @@
 				    "type": "static",
 				    "role": "iocs_agent"
 				}
-			    }
+			    },
+                "options": {
+                    "open_handshake_timeout": 2500,
+                    "close_handshake_timeout": 1000,
+                    "auto_ping_interval": 10000,
+                    "auto_ping_timeout": 5000,
+                    "auto_ping_size": 4
+                }
 			},
 			"call": {
 			    "type": "caller",

diff --git a/docker/crossbar/requirements.txt b/docker/crossbar/requirements.txt
diff --git a/docs/user/configuration.rst b/docs/user/configuration.rst
@@ -15,3 +15,4 @@ system. Details about configuring each are discussed in the following pages:
 
     site_config
     docker_config 
+    crossbar_config
diff --git a/docs/user/crossbar_config.rst b/docs/user/crossbar_config.rst
@@ -0,0 +1,120 @@
+.. _crossbar_config_user:
+
+======================
+Crossbar Configuration
+======================
+
+Overview
+========
+
+This page describes the crossbar server configuration file. This file defines
+the interface to the crossbar server.
+
+.. note::
+
+    For most test deployments of OCS, you should not need to modify this file
+    and can use the one that comes with the ``simonsobs/ocs-crossbar`` Docker
+    Image.
+
+Example Config
+--------------
+An example of the default OCS crossbar config that is bundled into
+``simonsobs/ocs-crossbar`` can be found in the repository at
+`ocs/docker/crossbar/config.json`_. This is based on the template in
+`ocs/ocs/support/crossbar_config.json`_.
+
+The unique parts of this to OCS are the realm name, "test_realm", defined
+roles of "iocs_agent" and "iocs_controller, and "address_root" of
+"observatory.". Additionally, we run on port 8001.
+
+For further details on crossbar server configuration, see the crossbar `Router
+Configuration`_ page.
+
+.. _`ocs/docker/crossbar/config.json`: https://github.com/simonsobs/ocs/blob/develop/docker/crossbar/config.json
+.. _`ocs/ocs/support/crossbar_config.json`: https://github.com/simonsobs/ocs/blob/develop/ocs/support/crossbar_config.json
+.. _`Router Configuration`: https://crossbar.io/docs/Router-Configuration/
+
+Generating a New Config File
+----------------------------
+``ocsbow`` can be used to generate a default configuration file, based on
+options in your OSC file, which can then be modified if needed.
+
+First, we make sure our ``OCS_CONFIG_DIR`` environment variable is set::
+
+    $ cd ocs-site-configs/
+    $ export OCS_CONFIG_DIR=`pwd`
+
+We should make a directory for the crossbar config, let's call it
+``dot_crossbar/`` (typically a dot directory, but for visibility we'll avoid
+that)::
+
+    $ mkdir -p ocs-site-configs/dot_crossbar/
+
+This directory needs to be configured as your crossbar 'config-dir' in your
+ocs-site-config file. Now we can generate the config::
+
+    $ ocsbow crossbar generate_config
+    The crossbar config-dir is set to:
+      ./dot_crossbar/
+    Using
+      ./dot_crossbar/config.json
+    as the target output file.
+    
+    Generating crossbar config text.
+    Wrote ./dot_crossbar/config.json
+
+You should now see a crossbar config file in ``./dot_crossbar/``. Make any
+modifications needed for your deployment.
+
+.. note::
+    The crossbar 'config-dir' block and the 'agent-instance' block defining the
+    'HostMaster' Agent are both required for the system you are running ocsbow on.
+    Be sure to add these to your SCF if they do not exist.
+
+Running with Docker
+===================
+
+We recommend running crossbar within a Docker container. We build the
+``simonsobs/ocs-crossbar`` container from the official `crossbar.io Docker
+image`_, specifically the cpy3 version. Bundled within the container is a
+simple OCS configuration that should work with the configuration
+recommendations in this documentation.
+
+If changes need to be made, then you will need to generate your own
+configuration file as described above. To use a modified configuration in the
+container you can either:
+
+- Edit the default configuration file and rebuild the Docker image
+- Mount the new configuration file over ``/ocs/.crossbar/config.json`` with the
+  proper permissions
+
+.. _`crossbar.io Docker image`: https://hub.docker.com/r/crossbario/crossbar
+
+Rebuilding the Docker Image
+---------------------------
+To rebuild the Docker image after modifying ``ocs/docker/config.json`` run::
+
+    $ docker build -t ocs-crossbar .
+
+You should then update your configuration to use the new, local,
+``ocs-crossbar`` image.
+
+Bind Mounting the Configuration
+-------------------------------
+To instead mount the new configuration into the pre-built image, first chown
+your file to be owned by user and group 242 (the default crossbar UID/GID),
+then mount it appropriately in your docker-compose file. Here we assume you
+put the configuration in the directory ``./dot_crossbar/``::
+
+    $ chown -R 242:242 dot_crossbar/
+
+Your docker-compose service should then be configured like::
+
+    crossbar:
+    image: simonsobs/ocs-crossbar
+    ports:
+      - "8001:8001" # expose for OCS
+    volumes:
+      - ./dot_crossbar:/ocs/.crossbar
+    environment:
+         - PYTHONUNBUFFERED=1
diff --git a/docs/user/docker_config.rst b/docs/user/docker_config.rst
@@ -31,24 +31,28 @@ components)::
       # Grafana for the live monitor.
       # --------------------------------------------------------------------------
       grafana:
-        image: grafana/grafana:5.4.0
+        image: grafana/grafana:latest
         restart: always
         ports:
           - "127.0.0.1:3000:3000"
-        environment:
-          - GF_INSTALL_PLUGINS=grafana-simple-json-datasource, natel-plotly-panel
         volumes:
           - /srv/grafana:/var/lib/grafana
 
+      # InfluxDB Backend for Grafana
+      influxdb:
+        image: influxdb:1.7
+        container_name: "influxdb"
+        restart: always
+        ports:
+          - "8086:8086"
+
       # --------------------------------------------------------------------------
-      # sisock Components
+      # Crossbar
       # --------------------------------------------------------------------------
       crossbar:
         image: simonsobs/ocs-crossbar:latest
         ports:
           - "127.0.0.1:8001:8001" # expose for OCS
-        volumes:
-          - ./config.json:/app/crossbar/config.json
         environment:
              - PYTHONUNBUFFERED=1
 
@@ -140,7 +144,7 @@ configuration.
     Pay attention to your version tags. "latest" is a convention in Docker to
     roughly mean the "most up to date" image. It is the default if a tag is
     left off. However, the "latest" image is subject to change. Pulling a "latest"
-    version today will not be guarenteed to get you the same image at another time.
+    version today will not be guaranteed to get you the same image at another time.
 
     What this means is for reproducability of your deployment, and perhaps for
     your own sanity, we recommend you use explicit version tags. Tags can be
@@ -171,5 +175,120 @@ For more details on configurations for individual containers, see the service
 documentation pages, for instance in the Agent Reference section.
 
 .. _reference: https://docs.docker.com/compose/compose-file/compose-file-v2/
-.. _sisock: https://github.com/simonsobs/sisock
 .. _`docker compose documentation`: https://docs.docker.com/compose/environment-variables/
+
+Considerations for Deployment
+-----------------------------
+The above examples are simple and meant to get you running quickly. However,
+they might not be the best configuration for deployment. One inconvenient thing
+is everything is managed in a single ``docker-compose.yml`` file. This means
+when you bring the system down, or restart it, all components are shutdown,
+this includes Grafana, which is one thing you might want running all the time,
+even if not actively collecting data with OCS, since you might want to look at
+past data. To achieve this you can separate the long-running services to
+different configuration files in separate directories, for instance::
+
+    .
+    ├── default.yaml
+    ├── docker-compose.yml
+    ├── influxdb
+    │   └── docker-compose.yml
+    └── crossbar
+        └── docker-compose.yml
+
+Where the separate compose files would look something like::
+
+    # influxdb/docker-compose.yml
+    version: '3.7'
+    networks:
+      default:
+        external:
+          name: ocs-net
+    services:
+      influxdb:
+        image: "influxdb:1.7"
+        container_name: "influxdb"
+        restart: always
+        ports:
+          - "8086:8086"
+        volumes:
+          - /srv/influxdb:/var/lib/influxdb
+
+::
+
+    # crossbar/docker-compose.yml
+    version: '3.7'
+    networks:
+      default:
+        external:
+          name: ocs-net
+    services:
+      crossbar:
+        image: simonsobs/ocs-crossbar:latest
+        restart: always
+        ports:
+          - "127.0.0.1:8001:8001" # expose for OCS
+        environment:
+             - PYTHONUNBUFFERED=1
+
+::
+
+    # web/docker-compose.yml
+    version: '3.7'
+    networks:
+      default:
+        external:
+          name: ocs-net
+    services:
+      grafana:
+        image: grafana/grafana:latest
+        restart: always
+        ports:
+          - "127.0.0.1:3000:3000"
+        volumes:
+          - /srv/grafana:/var/lib/grafana
+
+::
+
+    # docker-compose.yml
+    version: '3.7'
+    networks:
+      default:
+        external:
+          name: ocs-net
+    services:
+      ocs-aggregator:
+        image: simonsobs/ocs-aggregator-agent:latest
+        hostname: ocs-docker
+        user: "9000"
+        volumes:
+          - ${OCS_CONFIG_DIR}:/config:ro
+          - "/data:/data"
+        depends_on:
+          - "crossbar"
+
+      ocs-influx-publisher:
+        image: simonsobs/ocs-influxdb-publisher-agent:latest
+        hostname: ocs-docker
+        volumes:
+          - ${OCS_CONFIG_DIR}:/config:ro
+
+      ocs-LSA99ZZ:
+        image: simonsobs/ocs-lakeshore372-agent:latest
+        hostname: grumpy-docker
+        network_mode: "host"
+        volumes:
+          - ${OCS_CONFIG_DIR}:/config:ro
+        command:
+          - "--instance-id=LSA99ZZ"
+          - "--site-hub=ws://10.10.10.2:8001/ws"
+          - "--site-http=http://10.10.10.2:8001/call"
+
+Once the separate influxdb, crossbar, and web services are brought up, they
+should rarely need to be restarted, and are configured to automatically start
+at boot. This allows one to restart or shutdown the OCS Agents completely
+separately without worry of bringing down other components of the system.
+
+.. note::
+    This uses a Docker network, "ocs-net", which needs to be configured.
+    Details can be found in :ref:`multiconfig`.
diff --git a/docs/user/network.rst b/docs/user/network.rst
@@ -62,6 +62,8 @@ hardware.
     additional configuration, particularly if it needs to also communicate with the
     crossbar server.
 
+.. _multiconfig:
+
 Multiple-Configuration Files
 ````````````````````````````
 A single configuration file might be simple, however, for some containers it