Project Setup

Contents

Configuration

Project Directory

Configuration File

Project configuration file describes:

Example:

slowdash_project:
  name: ATDS
  title: Atomic Tritium Demonstrator at UW (ATDS)

  data_source:
    type: PostgreSQL
    parameters:
      url: p8_db_user:****@localhost:5432/p8_sc_db
      time_series:
        schema: data_table[channel]@timestamp=value

  style:
    theme: light
    title:
      color: white
      background: "#4b2e83"

  system:
    file_mode: 0666

Data Source Entry (data_source, often necessary)

Module Entry (module, optional)

Style Entry (style, optional)

See Styles below.

System Entry (system, optional)

Authenticate Entry (authenticate, for special purposes)

See Security Considerations below.

Styles

Configuration

Title-bar Style Example

  style:
    title:
      background: linear-gradient(125deg, rgba(75,46,131,1), rgba(75,46,131,1), rgba(75,46,131,0.9))
    logo:
      file: P8_Logo_2017.png
      position: left
      background: linear-gradient(90deg, rgba(255,255,255, 0.6), rgba(255,255,255, 0.4), rgba(255,255,255, 0))

The background property takes CSS “background” values / expressions. See, e.g., a Mozilla document for some examples.

The logo file(s) must be placed under the project config directory.

Plot Style Examples

Default Style

Dark Theme

  style:
    theme: dark

Custom Style

  style:
    panel:
      plotTicksOutwards: true
      plotFrameThickness: 0
      plotBackgroundColor: "#f0f0f0"
      plotGridColor: gray

Testing the Configuration

Running the slowdash command without the --port option takes parameters from the arguments and prints output to screen. Run the command at the same directory as the configuration file is located.

Printing the Configuration

$ slowdash config
{
    "project": {
        "name": "ATDS",
        "title": "Atomic Tritium Demonstrator at UW (ATDS)",
        "error_message": ""
    },
    ...
}

Printing Channel List

$ slowdash channels
23-03-22 12:48:34 INFO: loaded datasource module "datasource_SQLAlchemy"
[
  {"name": "sccm_Alicat_Inj_Gas"}, 
  {"name": "mbar_CC10_Inj_Gas"}, 
  {"name": "mbar_IG_Vac_MS"}, 
  {"name": "degC_RTD1_Acc_AS"}, 
  {"name": "degC_RTD2_Acc_AS"}, 
  ...

Printing Data

$ slowdash 'data/sccm_Alicat_Inj_Gas?length=60'
23-03-22 12:50:20 INFO: loaded datasource module "datasource_SQLAlchemy"
{
  "sccm_Alicat_Inj_Gas": {
    "start": 1679514341, "length": 60, 
    "t": [2.364, 12.364, 22.355, 32.366, 42.364, 52.362], 
    "x": [-0.015, -0.014, -0.014, -0.015, -0.014, -0.016]
  }
}

When the argument includes a special character of the shell (such as ? and &), quote the entire argument.

Running the Server

WARNING: Slow-Dash is designed for internal use within a secured network and therefore no security protection is implemented. It is strongly recommended not to expose the system to the public internet. External access is assumed to be done through VPN or ssh tunnel.

Run as a User Process

$ slowdash --project-dir=PROJECT_DIR --port=18881

Run in a Docker Container

[TODO]

Launch from CGI

Slowdash can be executed as CGI of a web server such as Apache or Nginx. To setup this, run the script below at the project directory:

$ slowdash-setup-web
Project: ATDS
Project directory: /home/sanshiro/Project8/SlowDash/Projects/ATDS
Web-file directory: /home/sanshiro/public_html/SlowDash/ATDS
continue? [Y/n] y
Web-file directory created: /home/sanshiro/public_html/SlowDash/ATDS

=== INSTALLATION IS SUCCESSFUL ===
*) To setup SLOWDASH Web for another project, set SLOWDASH_PROJECT and run this program.
*) It is safe to run this slowdash-setup-web multiple times, even for the same project.
*) Web interface can be disabled by deleting the web-file directory.
*) Disabled Web interface can be re-enabled by running this program again.
*) Web-file directory for this project: /home/sanshiro/public_html/SlowDash/ATDS

The script will copy all the necessary files under user’s web directory (typically /home/USER/public_html) and create .htaccess with the contents below:

DirectoryIndex home.html
Options +ExecCGI
AddType application/x-httpd-cgi .cgi
AddHandler cgi-script .cgi
AddType text/javascript .mjs

RewriteEngine On
RewriteRule ^api/(.*)$ slowdash.cgi/$1

The web server must be configured so as to:

Advantages

Disadvantages

User modules are disabled for CGI by default. To use a module with CGI, set the cgi_enabled parameter true in the module configuration. Be careful for all the side effects, including performance overhead and security concerns.

Security Considerations

As already mentioned, SlowDash is designed for internal use only within a secured network and therefore no security protection is implemented. It is strongly recommended not to expose the system to the public internet. External access is assumed to be done through VPN or ssh tunnel.

Basic Authentication

In a sad case that you cannot trust your internal friends, the “Basic Authentication” can be used. Combine the authentication with HTTPS using a reverse proxy to encrypt the password and communication.

To use the Basic Authentication, first install the bcrypt Python package if it is not yet installed:

$ pip3 install bcrypt

Then generate an authentication key by slowdash authkey/USER?password=PASS:

$ slowdash authkey/slow?password=dash
{
    "type": "Basic",
    "key": "slow:$2a$12$UWLc20NG5E3drX35cfA/5eFxuDVC0U79dGg4UP/mo55cj222/vuRS"
}

Add the key in the project configuration file under the authentication entry:

slowdash_project:
  ...

  authentication:
    type: Basic
    key: slow:$2a$12$UWLc20NG5E3drX35cfA/5eFxuDVC0U79dGg4UP/mo55cj222/vuRS

This key can also be used for Apache, although some Apache keys, especially old ones such as MD5 keys which are still widely used, can not be used for SlowDash.

Only for the CGI mode

Rerun the slowdash-setup-web.py command to update the Web Server configuration.

$ slowdash-setup-web
Project: ATDS
Project directory: /home/sanshiro/Project8/SlowDash/Projects/ATDS
Web-file directory: /home/sanshiro/public_html/SlowDash/ATDS
User: slow
continue? [Y/n] y
...

Note that a new line, User: slow, is now added.