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, use0.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.
Environment Variables ↑
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-*' ]
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