server.yaml#

The server.yaml file is used to configure various aspects of the MXCuBE’s back-end server. The configuration file contains the following sections:

server
mxcube

See below an example server.yaml file.

server#

The server section primarily deals with the configuration of the network aspects of the back-end server. It allows customizing the behavior of the Flask framework, its plugins and other components. The section has the following syntax:

server:
  DEBUG: <boolean>
  SECRET_KEY: <secret key>
  SECURITY_PASSWORD_SALT: <password salt>
  SECURITY_TRACKABLE: <boolean>
  PERMANENT_SESSION_LIFETIME: <session lifetime>
  USER_DB_PATH: <db_file_path>
  CERT_KEY: <certificate key file path>
  CERT_PEM: <certificate pem file path>
  CERT: <ssl_mode>
  ALLOWED_CORS_ORIGINS:
    - <allowed URL>
    - <allowed URL>
    ...

The server section may contain keys as described below.

`DEBUG`#

Whether Flask debug mode is enabled. This is the equivalent of Flask’s DEBUG configuration value.

Default value is False.

`SECRET_KEY`#

Flask’s security signing key, for example for signing session cookies. This is the equivalent of Flask’s SECRET_KEY configuration value.

`PERMANENT_SESSION_LIFETIME`#

Session cookie’s lifetime. This is the equivalent of Flask’s PERMANENT_SESSION_LIFETIME configuration value.

`SECURITY_PASSWORD_SALT`#

Password hashing salt. This is the equivalent of Flask-Security-Too’s SECURITY_PASSWORD_SALT configuration value.

`SECURITY_TRACKABLE`#

Enables tracking of basic user login statistics. This is the equivalent of Flask-Security-Too’s SECURITY_TRACKABLE configuration value.

Default value is True.

`USER_DB_PATH`#

Full path to SQLite database file, used for storing users and sessions data.

Default value is /tmp/mxcube-user.db.

`ALLOWED_CORS_ORIGINS`#

List of origins that are allowed to connect to this server. This list is passed via cors_allowed_origins parameter to the SocketIO class constructor. Note that if this list is too restrictive, the front-end will fail to create a SocketIO connection to the back-end.

For most cases, the default behavior, which is provided by setting this value to an empty list [], is good enough. Indeed it disallows any cross-site requests, but of course it still allows same-site requests. For MXCuBE-Web, there is very likely no need for cross-site requests. Allowing cross-site requests can be a source of security issues.

`CERT`#

Used to enable SSL and set the type of host certificate. The following values are supported:

NONE	SSL disabled
ADHOC	SSL enabled, autogenerated certificate is used
SIGNED	SSL enabled, signed certificate is used

Default value is NONE.

`CERT_PEM`#

Path of the certificate file to use for SSL connections.

`CERT_KEY`#

Path of the private key file to use for SSL connections.

`CSP_ENABLED`#

Enable or disable Content Security Policy (CSP) headers for the server. When set to true, CSP headers are sent with responses according to the policy defined in CSP_POLICY.

Default value is false.

`CSP_POLICY`#

Defines the Content Security Policy (CSP) rules applied by the server. This should be a mapping of CSP directives to lists of allowed sources.

`CSP_REPORT_ONLY`#

If set to true, the CSP policy is only reported (not enforced). Violations are sent to the URI specified by CSP_REPORT_URI.

Default value is false.

`CSP_REPORT_URI`#

Specifies the URI where CSP violation reports are sent when CSP_REPORT_ONLY is enabled.

Default value is /mxcube/api/v0.1/csp/report.

`GRAYLOG_HOST`#

Hostname or IP address of the Graylog server for logging. Set to null to disable Graylog logging.

Default value is None.

`GRAYLOG_PORT`#

Port number of the Graylog server for logging. Set to null to disable Graylog logging.

Default value is None.

mxcube#

The mxcube section allows you to customize miscellaneous aspects of the MXCuBE application. It contains settings for the on-axis video stream, user account management, and experiment mode. The section has the following syntax:

mxcube:
  mode: <experiment mode>
  USE_EXTERNAL_STREAMER: <boolean>
  VIDEO_FORMAT: <format name>
  VIDEO_STREAM_URL: <stream URL>
  VIDEO_STREAM_PORT: <stream port>
  SESSION_REFRESH_INTERVAL: <refresh interval>
  usermanager:
    class: <class name>
    inhouse_is_staff: <boolean>
    users:
      - username: <user name>
        role: <role name>
      ...

The mxcube section may contain keys as described below.

`mode`#

Set the experiment mode for the application. Different modes tailor the presented UI to be suitable for a specific type of MX experiments. The following values are supported:

mode	experiment type
OSC	standard oscillation data collection
SSX-CHIP	SSX fixed target experiments
SSX-INJECTOR	SSX injector experiments

Default mode is OSC.

`USE_EXTERNAL_STREAMER`#

Use an external process to stream the sample view video. When enabled, MXCuBE will invoke an appropriate hook on the camera hardware object to start the streamer. It is assumed that the camera object supports the external streamer feature.

Default value is False.

`VIDEO_FORMAT`#

The format to use when streaming the sample view video. The MPEG1 and MJPEG formats are supported. Note that your camera hardware object must support the specified format.

Default format is MPEG1.

`VIDEO_STREAM_URL`#

The URL that is used by the UI to fetch the sample view video. When set, it will override the default video stream URL. This configuration is primarily useful with external streams, that provide video stream from custom URLs.

`VIDEO_STREAM_PORT`#

This configuration is used when USE_EXTERNAL_STREAMER flag is enabled. The specified value is passed on to the camera hardware object, when invoking the start stream hook.

`SESSION_REFRESH_INTERVAL`#

The interval in milliseconds at which the front-end makes requests to refresh the session.

Default interval is 9000 milliseconds.

`usermanager`#

This subsection allows configuring user management in the application.

class specifies the class name of the user manager. This allows using a custom implementation of the user manager if needed.

The default class name is UserManager.

inhouse_is_staff specifies if all in-house users should automatically acquire staff role. Which users are considered in-house is managed by the session hardware object.

The default value is True.

users specifies users that should acquire additional roles. The content of this key is a list of username and role specifications. Currently, only the staff role can be specified.

server.yaml example#

Below is an example of a server configuration file server.yaml, as used by the mockup beamline.

---

server:
  SECRET_KEY: ASECRETKEY
  SECURITY_PASSWORD_SALT: ASALT
  PERMANENT_SESSION_LIFETIME: 60
  CERT: NONE

  DEBUG: false

  ALLOWED_CORS_ORIGINS: []
  HOST: "127.0.0.1"
  PORT: 8081
  USER_DB_PATH: /tmp/mxcube-user.db

  CSP_ENABLED: true
  CSP_POLICY:
    default-src:
      - "self"
    script-src:
      - "self"
      - "unsafe-inline"
      - "unsafe-eval"
    style-src:
      - "self"
      - "unsafe-inline"
    img-src:
      - "self"
      - "data:"
      - "blob:"
    font-src:
      - "self"
    connect-src:
      - "self"
      - "wss:"
      - "ws:"
    frame-src:
      - "self"
    object-src:
      - "none"
    base-uri:
      - "self"
    form-action:
      - "self"
  CSP_REPORT_ONLY: false
  CSP_REPORT_URI: "/mxcube/api/v0.1/csp/report"

  GRAYLOG_HOST: None
  GRAYLOG_PORT: None

sso:
  USE_SSO: false
  ISSUER: https://websso.[site].[com]/realms/[site]/
  LOGOUT_URI: ""
  TOKEN_INFO_URI: ""
  CLIENT_SECRET: ASECRETKEY
  CLIENT_ID: mxcube
  SCOPE: openid email profile
  CODE_CHALLANGE_METHOD: S256

mxcube:
  USE_EXTERNAL_STREAMER: true
  VIDEO_FORMAT: MPEG1
  VIDEO_STREAM_URL: ws://localhost:8000/ws

  # At which port to stream from
  VIDEO_STREAM_PORT: 8000
  # Mode, SSX-CHIP, SSX-INJECTOR, OSC
  mode: OSC

  USE_GET_SAMPLES_FROM_SC: true
  # This is used to determine whether we can get samples from the sample changer
  # if false, Only LIMS samples will be availble to fetch for the sample list

  # Interval with which request to refresh token is made
  # by the client application.
  SESSION_REFRESH_INTERVAL: 9000

  usermanager:
    class: UserManager
    inhouse_is_staff: true
    users:
      - username: opid291
        role: staff

server.yaml#

server#

DEBUG#

SECRET_KEY#

PERMANENT_SESSION_LIFETIME#

SECURITY_PASSWORD_SALT#

SECURITY_TRACKABLE#

USER_DB_PATH#

ALLOWED_CORS_ORIGINS#

CERT#

CERT_PEM#

CERT_KEY#

CSP_ENABLED#

CSP_POLICY#

CSP_REPORT_ONLY#

CSP_REPORT_URI#

GRAYLOG_HOST#

GRAYLOG_PORT#