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:

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.

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.

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>
  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.

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:
    - http://localhost:8081
    - http://127.0.0.1:8081
    - http://localhost:5173
    - http://127.0.0.1:5173
    - ws://localhost:8000
    - ws://127.0.0.1:8000

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

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