Boomack Server

The command for the Boomack Server is boomack.

The Boomack Server can be configured in three ways: command line switches, environment variables, and configuration files. They can all be used in combination and are merged with a certain priority.

Command line switches
Environment variables
Config files
Default configuration

Command Line Switches ↑

Specific switches
- -h, --host <Host IP>
  The IP address to listen to. Default: 127.0.0.1
  To listen to all IPv4 addresses on all interfaces, use 0.0.0.0. To listen to all IPv6 and potentially all IPv4 addresses, use ::.
- -p, --port <Port>
  The port to listen to. Default: 3000
- -v, --verbose
  Sets the logging level to verbose.
- -q, --quite
  Sets the logging level to warning.
Generic switch
- -o, --option <Key>=<Value> [<Key>=<Value>]*
  Can be followed by multiple key-value-pairs of options. Can be used multiple times in one command line. The key in the key-value-pair is the path in the configuration tree with a dot . as separator.
  
  Examples:
  --option log.level=warn
  -o "web.brand.title=Demo Site"
  -o plugins.packages.0=boomack-plugin-vega plugins.packages.1=boomack-plugin-pdf
Startup switches
- --logo / --no-logo
  Activates / deactivates printing logo and version number on startup.
- -b, --browser
  Opens the web client in your default web browser.
- -d, --panel <panel ID>
  Specifies the panel to open, if --browser is used.

All environment variables with the prefix BOOMACK_ are considered to be configuration options. The path of the option in the configuration tree is parsed from the remaining variable name after the prefix with the underscore _ as separator.

Examples:

BOOMACK_SERVER_HOST
BOOMACK_LOG_LEVEL
BOOMACK_plugins_packages_0, BOOMACK_plugins_packages_1
BOOMACK_API_enable_actions

The parts of the path in the configuration tree can be written all upper case, or real case. If the part in the configuration tree contains lower and upper case characters, it must be written in in real casing in the environment variable.

E. g. the path server → host contains no upper case characters. Therefore, it can be specified with the environment variable BOOMACK_server_host or BOOMACK_SERVER_HOST. The path storage → snapshotInterval, on the other hand, contains upper case characters in the second part. Therefore, it can be specified with BOOMACK_storage_snapshotInterval or BOOMACK_STORAGE_snapshotInterval.

Config Files ↑

The Boomack Server considers multiple configuration files on startup and combines them with certain priorities.

Config files specified on the command line with --config or -c are processed in reverse order: lastly specified config file has highest priority
A Config file boomack-server[.json|.yaml|.yml] in the current working directory
A Config file in the user profile .boomack-server[.json|.yaml|.yml]
The default config file in the source code of the server

Config files specified on the command line must exist, otherwise the server will not start. The config files in the current working directory and user profile are considered only if they exist.

The config files in the current working directory and the user profile can have no filename extension or one of the following: .json, .yaml, .yml. And they are lookup up in that order. Meaning, if a file boomack-server in the current working directory exists, another file with name boomack-server.yaml will be ignored.

Configuration files are parsed with a YAML parser. Therefore, they may contain JSON — wich is a subset of YAML — but can use all other syntax features of YAML v1.1 as well. However, if they have the filename extension .json, they should contain proper JSON only.

Configuration Topics ↑

API Authentication ↑

To activate the API authentication, the option api.auth.mode must be set to "token". Additionally under the path api.auth.tokens at least one token must be configured. The access token string is the key of an entry in the map under api.auth.tokens. The value of the entry is another map for further configuration of the token.

By default a token has unlimited access to the API. This can be restricted by referencing a role from api.auth.roles in the role property of the token map. Individual access rights can be overridden under the property access. And last to limit the access to a certain group of panels, the panels property with an array if panel IDs can be used. The panel IDs support the wildcard *.

Minimal example for a super-user token:

api:
  auth:
    mode: token
    tokens:
      'edc3eacdb404143ad12a1eb2e667': {}

Example with a role publisher and a token, restricted to read-only-access and display requests on the panels default and limited-*:

api:
  auth:
    mode: token
    roles:
      'publisher':
        panels: { list: true, get: true, create: false, layout: false, delete: false }
        content: { display: true, clear: true, evaluate: false }
        presets: { list: true, get: true, create: false, update: false, delete: false }
        types: { list: true, get: true, create: false, update: false, delete: false }
        actions: { list: true, get: true, create: false, update: false, delete: false }
        export: { all: false, panel: false, slot: false }
    tokens:
      'edc3eacdb404143ad12a1eb2e667':
        role: 'publisher'
        panels: [ 'default', 'limited-*' ]

Important: If authentication is activated, the HTTP endpoint must be published with TLS encryption only! Otherwise the secret tokens get transmitted unencrypted over the network. Because Boomack does not come with TLS encryption at the time, a reverse-proxy must be used.

Hint: It can be useful to put the authentication configuration in a separate config file. E. g. auth.yaml. Then it can be passed to the Boomack Server on startup with the command line switch --config auth.yml.

Default Configuration ↑

Until the server configuration is documented in more detail, the default config with comments is included here for reference.

# Boomack Server Default Configuration

server:
  # The IP address of the interface the server should listen on
  # E.g. localhost, 127.0.0.1, 192.168.123.1, or 0.0.0.0
  host: '127.0.0.1'
  # The port to listen on
  port: 3000
  # The URL to reach the server by, if the server is made public via a reverse proxy
  # E.g. https://boomack.internal.company.com/srv1/
  url: null

log:
  # The log level: verbose, info, warn, error
  level: info

# The top-level property 'client' is reserved for API client configuration.

boot:
  # Open the URL of the server in the default browser of the os
  open: false
  # The ID of the initial panel to open in the browser
  # Opens the home page if no panel ID is given
  panel: null

storage:
  # supported modes: 'none', 'snapshot-files'
  mode: none

  # A path to the directory to store the server state in
  location: state

  # The interval of recording snapshots in seconds
  snapshotInterval: 60

web:
  # the name of the default theme
  theme: default

  # customize the branding
  brand:
    # the title for the server
    title: Boomack
    # a filesystem path to an image on the server, default is the themed Boomack logo
    logo: null
    # a filesystem path to an image on the server, default web.brand.logo
    logoDark: null
    # a filesystem path to an *.ico file on the server, default is the Boomack logo
    favicon: null

  home:
    # the ID of a panel to redirect from the home page
    # prevents the panel list from showing
    redirect: null

  cache:
    # max age in cache control for static resources
    # duration in ms format: https://www.npmjs.com/package/ms
    static: 24h

  static:
    # a number of folders to host as static files
    #
    # example for hosting /tmp/www under http://<boomack-server>/static/demo
    # caching with max age of 10 minutes (duration in ms format: https://www.npmjs.com/package/ms)
    #
    # demo:
    #   path: /tmp/www
    #   cache: 10m                             # optional
    #   index: ['index.html', 'default.html']  # optional
    #
    # Warning: If authentication is activated for the web interface,
    #          all users have read access to all static files.

  # authentication for the web client
  auth:
    # supported modes: 'none', 'basic', 'standard'
    mode: none
    # The realm, displayed by the browser, when it prompts for credentials
    # in 'basic' authentication mode.
    realm: Boomack
    # A secret string for HMAC signatures in authentication mode 'standard'.
    # If left empty, a random secret is created every time the server starts.
    # As a result, users must re-login, when the server is restarted.
    # Use a string with at least 20 random chars.
    secret: null
    # The number of seconds, after which a login is invalidated.
    # If left empty or set to 0, logins are valid 1000 years.
    lifetime: 86400
    # An array with users, allowed to navigate the web client
    users:
    - name: boomack
      # set the password as SHA256 hash in HEX encoding prefixed with 'sha256:'
      # example for 'boomack':
      passwordHash: 'SHA256:2D7BA851D5BDFBDA0F13463543021616584E823C3B2116EA0D0F2A6A0D6F41F4'
      # restrict access to certain panels
      panels: ['default', 'another-panel']

api:
  # activate/deactivate groups of API routes
  enable:
    # activate routes for changing slot content
    content: true
    # activate routes for requesting JS code evaluation in panels
    evaluation: true
    # activate routes for creating/deleting and changing layout of panels
    panels: true
    # activate routes for managing presets
    presets: true
    # activate routes for managing MIME types
    types: true
    # activate routes for managing actions
    actions: false
    # activate routes for exporting to local filesystem
    export: false

  # authentication for the API
  auth:
    # supported modes: 'none', 'token'
    mode: none
    # A map of access roles
    roles:
      # The role 'default' is hardcoded but can be adapted here
      # it is the default role of a token, in case no other role is specified
      # default:
      #   panels:
      #     list: true
      #     get: true
      #     create: true
      #     layout: true
      #     delete: true
      #   content:
      #     display: true
      #     clear: true
      #     evaluate: true
      #   presets:
      #     list: true
      #     get: true
      #     create: true
      #     update: true
      #     delete: true
      #   types:
      #     list: true
      #     get: true
      #     create: true
      #     update: true
      #     delete: true
      #   actions:
      #     list: true
      #     get: true
      #     create: true
      #     update: true
      #     delete: true
      #   export:
      #     all: true
      #     panel: true
      #     slot: true

    # An array of tokens
    tokens:
      # use the token as the key to ensure uniqueness
      'A long secret ASCII string':
        # assign role, if none is given 'default' is used
        role: default
        # override access from role
        access:
          actions:
            create: false
            delete: false
        # restrict access to certain panels with wildcard
        panels: ['default', 'prefixed-*']

  request:
    # A switch to activate processing requests without content type
    withoutContentType: true
    # A switch to activate YAML support in requests
    yaml: true
    # The size limit for API requests in JSON or YAML
    maxBodySize: 16 MB
    # A list with allowed root paths for file URLs in display requests.
    # Allows displaying files directly from the filesystem of the server.
    # Empty by default for security reasons.
    # Examples: /home/me/media, or C:\\Users\\Me\\Pictures
    fileSrcRoots: []

cache:
  # Control how cached resources are handled
  memory:
    limit:
      # The limit for all in-memory resources from all panels
      global: 128 MB
    autoThreshold:
      # The minimal size of non-text data to be automatically
      # cached as a memory resource, instead of being embedded
      global: 256 KB

  files:
    # A path to a directory, to store cache files in.
    # Defaults to a folder 'boomack' inside the OS temp directory,
    # or the folder 'fileres' in the state directory,
    # if storage mode is set to 'snapshot-files'.
    location: null
    limit:
      # The limit for all file resources from all panels
      global: 1 GB
    autoThreshold:
      # The minimal size of non-text data to be automatically
      # cached as a file resource
      global: 4 MB

plugins:
  # The root directory where to find plugin packages.
  # If not set, npm is used to find the global node_modules folder.
  root: null
  # Search the plugin root for plugin packages.
  # If plugins.root is not set, searches for globally installed packages.
  # Plugin packages must start with 'boomack-plugin-'.
  discover: false
  # A list with node package names of plugins to use.
  packages: []

export:
  # Exports to the local filesystem at the server
  local:
    # A path to a directory to export to
    # If null, does not allow exports to local filesystem
    location: null
    # The maximal size for accumulated resources to be included in exports
    resourceSizeLimit: null

  # Exports as ZIP from the web user interface
  zip:
    # The maximal accumulated size for resources to be included in exports
    resourceSizeLimit: 1536 MB

init:
  # A map with initial panels
  panels:
    # one panel must have the ID "default"
    "default":
      # show or hide the header above the slots
      header: true
      # the size of the header, if visible: mini, tiny, small, medium, large, huge, massive
      headerSize: medium
      # select a theme for this panel: default, dark
      theme: default
      # select a theme variation for this panel: full, slim
      themeVariation: full
      # CSS code to be included in the HTML head of the panel
      style: null
      # JavaScript code to be executed when the panel was loaded
      script: null
      # the ID of the default slot (optional)
      defaultSlot: null
      # the initial default panel has a minimal grid layout
      grid:
        columns: 1
        rows: 1
      slots:
        # if not explicitly defined, first slot is the default slot
        "default":
          history: 10
          extensions: 100
          border: true
          toobar: true
          noZoom: false
          noClear: false
          noMaximize: false
          noSingleOut: false
          showId: true
          colorFilter: null
          column: 0
          row: 0
          columnSpan: 1
          rowSpan: 1

  # A map with initial actions
  actions: { }
  #  action-id:
  #    type: shell
  #    # The shell command and an array with command line arguments
  #    command: python3
  #    args: ['my-script.py']
  #    # The way to use the payload: discard, args, stdin, command
  #    payload: args

  # A map with initial presets
  presets: { }
    # example preset for transformed text with additional presentation options
    #  headline:
    #    transformation: uppercase
    #    align: middle center
    #    background: #FFC080

  # A map with initial MIME types
  types: { }
    # example type for a syntax highlighted text file
    # "text/css":
    #   presets: []
    #   options:
    #     syntax: css

Boomack Server

Command Line Switches ↑

Environment Variables ↑

Config Files ↑

Configuration Topics ↑

API Authentication ↑

Default Configuration ↑