Deployment

Open Pectus comprises of two pieces of software:

  1. Engine running on a computer which is connected to process equipment

  2. Aggregator running centrally

The deployment of these components is described in the following.

Deployment of Engines

Installation

Open Pectus supports Windows and Linux and can be installed as follows:

  1. Download and install Miniconda

  2. Create a Conda environment, activate it and install Open Pectus by opening the Miniconda prompt and running:

    conda env create --name openpectus python==3.11
conda activate openpectus
pip install openpectus

  3. (Optional) Set the SENTRY_DSN environment variable:

    To enable the Sentry logger, the SENTRY_DSN environment variable needs to be set. Save the value as an environment variable on your developer pc:

    setx SENTRY_DSN value

Running an Engine

With Open Pectus installed it is possible to start an engine using the Miniconda prompt with the pectus-engine command.

The following example starts an engine using a UOD at C:\process_uod.py and connects to an aggregator running at openpectus.com with SSL encryption.

conda activate openpectus
pectus-engine -s -ahn openpectus.com -uod C:\process_uod.py

See pectus-engine Command Reference for documentation of the pectus-engine command.

Deployment of Aggregator

While it is possible to run an aggregator instance as-is it is highly recommended to use the provided Docker image.

The following instructions assume that the host system runs Ubuntu although Docker is available on many platforms.

Installation

Install Docker, nginx and certbot. Docker is used to run the container, nginx is a reverse proxy with SSL support and certbot provides free SSL certificates through letsencrypt.

A domain name and SSL certificate are not specifically required by Open Pectus. The User Authorization (OIDC) integration does depend on encryption (which requires a domain name) though.

sudo apt update
sudo apt install curl apt-transport-https ca-certificates software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce nginx-full certbot -y

Configuration

Permissions

To allow non-root user azureuser to use Docker:

sudo usermod -aG docker azureuser
newgrp

Close terminal session. In a new session the user will be allowed. Test by issuing docker version.

Firewall

On systems with ufw http and https traffic might be blocked unless allowed:

sudo ufw allow http
sudo ufw allow https

Nginx

Edit /etc/nginx/sites-enabled/default to be something like Listing 2. Restart nginx afterwards to load the configuration sudo /etc/init.d/nginx restart.

Listing 2 Nginx configuration /etc/nginx/sites-enabled/default
 server {
     # Delete from here <--
     if ($host = openpectus.com) {
         return 301 https://$host$request_uri;
     } # managed by Certbot
     # --> to here if you do not use ssl.
     listen 80;
     server_name openpectus.com;
     location / {
         proxy_pass http://127.0.0.1:8300;
         # WebSocket support
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";
         proxy_read_timeout 86400;
     }
 }

 server {
     listen 443 ssl;
     server_name openpectus.com;
     ssl_certificate /etc/letsencrypt/live/openpectus.com/fullchain.pem; # managed by Certbot
     ssl_certificate_key /etc/letsencrypt/live/openpectus.com/privkey.pem; # managed by Certbot
     location / {
         proxy_pass http://127.0.0.1:8300;
         # WebSocket support
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";
         proxy_read_timeout 86400;
     }
 }

Certbot

Acquire SSL certificates using certbot:

certbot certonly --manual --preferred-challenges dns --register-unsafely-without-email

This command should be run periodically to avoid expiration.

Running an Aggregator

Commands to pull latest image and run it are given below. The docker run command options are:

  • --pull=always --detach, pulls latest image and runs it in detached state

  • --name openpectus-prd, allows reference to the the container by name openpectus-prd in other Docker commands.

  • -h AZR-PECTUS-PRD, sets the hostname. The aggregator host name appears in the CSV File Format metadata.

  • -v /home/azureuser/data_prd:/data, mounts the directory containing the database to /home/azureuser/data_prd on the host. This is necessary in order to persist the database across different versions of the Docker image.

  • -e AZURE_APPLICATION_CLIENT_ID='...', -e AZURE_DIRECTORY_TENANT_ID='...' and -e ENABLE_AZURE_AUTHENTICATION='true' configure the User Authorization (OIDC) integration.

  • -e SENTRY_DSN='...', sets the Sentry DSN and enables error logging to Sentry.

  • -p 0.0.0.0:8300:8300/tcp, maps port 8300 of the container to the host.

docker run --pull=always --detach \
--name openpectus-prd \
-h AZR-PECTUS-PRD \
-v /home/azureuser/data_prd:/data
-e AZURE_APPLICATION_CLIENT_ID='...' \
-e AZURE_DIRECTORY_TENANT_ID='...' \
-e ENABLE_AZURE_AUTHENTICATION='true' \
-e SENTRY_DSN='...' \
-p 0.0.0.0:8300:8300/tcp \
ghcr.io/open-pectus/open-pectus:main

  • List running containers using docker ps

  • To attach to a running container docker attach openpectus-prd To detach press <CTRL>+P+Q

  • To stop the container docker stop openpectus-prd

  • To delete the container docker rm openpectus-prd

  • To delete the image docker image ls and docker rm image-hash

Aggregator Database Administration

The Open Pectus aggregator uses sqlite as database backend.

The Database Administration tool is a useful web interface which enables simple management of the sqlite database. The tool can integrated with User Authorization (OIDC) in which case a client secret must be provided and users who should have access must be assigned to an “Administrator” App Role. A docker image is provided which can be run using the command below:

docker run --pull=always --detach \
--name openpectus-database-administration \
-h AZR-PECTUS-PRD-DATABASE-ADMINISTRATION \
-v /home/azureuser/data_prd:/data
-e AZURE_APPLICATION_CLIENT_ID='...' \
-e AZURE_DIRECTORY_TENANT_ID='...' \
-e AZURE_CLIENT_SECRET='...' \
-e ENABLE_AZURE_AUTHENTICATION='true' \
-p 0.0.0.0:8301:8301/tcp \
ghcr.io/open-pectus/database-administration:main

Add the following to the “server”-blocks of Listing 2 to access the web interface at https://openpectus.com/admin/.

location /admin/ {
    proxy_pass http://127.0.0.1:8301;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffer_size 128k;
    proxy_buffers 8 128k;
    proxy_busy_buffers_size 256k;
}

Database Backup

It is possible to do a database backup of a running aggregator by executing the following command on the host running the Docker container:

sqlite3 /home/azureuser/data_prd/open_pectus_aggregator.sqlite3 ".backup '/home/azureuser/tmp.sqlite3'"; mv /home/azureuser/tmp.sqlite3 /home/azureuser/open_pectus_aggregator_prd-$(date +"%Y-%m-%d").sqlite3

A cron job can be configured to make a backup on a daily basis and only keep the last 30 copies. Create the folder /home/user/data_prd_backup, edit the cron table with crontab -e and add the following:

5 4 * * * sqlite3 /home/azureuser/data_prd/open_pectus_aggregator.sqlite3 ".backup '/home/azureuser/tmp.sqlite3'"; mv /home/azureuser/tmp.sqlite3 /home/azureuser/data_prd_backup/open_pectus_aggregator_prd-$(date +"%Y-%m-%d").sqlite3
5 5 * * * rm -f $(ls -1t /home/azureuser/data_prd_backup/ | tail -n +31)