Server Configuration Options

While a Blocks server often works fine as is, there are a number of configuration options that can be changed to further tailor the system to your network and other requirements. Configuration can be applied in the following two ways:

• By changing configuration options for the Blocks server itself. This is done through a configuration file read by the Blocks server as it starts up.
• By changing operating system settings to activate other, complementary features, such as DNS, DHCP, remote access, enterprise wifi network integration, etc. Such configuration is done in other parts of the system, and is mainly supported when running on a Linux server.

You can configure Blocks using a configuration file. There are two possible locations and names for this file:

1. In the home directory of the user account under which Blocks runs, named PIXILAB-Blocks-config.yml.
2. Inside Blocks' data folder, then named config.yml. Blocks' data folder must in this case be named “PIXILAB-Blocks-root”, and located in the home directory of the user account under which Blocks runs.

NOTE: On our Linux-based server, this home directory is at /home/pixi-server/.

Here’s an example of what you may find in this file:

# Location of Blocks' data folder.
# IMPORTANT: If changed, you must also update any nginx configuration
# accordingly. See under "Alternative Blocks Root Directory" below.
root: /home/pixi-server/PIXILAB-Blocks-root

# Where to go when addressing root of server (i.e., just http://pixi.guide/)
serverRootRedirect: /spot/?mobile=Mob1

defaultSpotCSS: styles/invis-buttons.css

# Main server configuration
server:
  type: pixilab_server
  #corsPath: /rest/script/invoke/*
  #corsAllowOrigin: "*"

  applicationConnectors:
    - type: http
      port: 8080
      useForwardedHeaders: true  # Needed if running behind a reverse proxy
 
  #auth:    # Uncoment to control authorization settings explicitly
  #  servlet:
  #    security:
  #      - matchers: internalMatcher
  #        authorizers: isAuthenticated
  #        clients: internalDigest  # internalDigest internalForm OidcClient
     
scripting:
  watchFiles: true

logging:
  # The default level of all loggers, such as OFF, ERROR, WARN, INFO
  level: WARN

  loggers:
    Realm: INFO # Log task log statements messages, regardless of originating Realm
    Script: INFO # Log "console.log" messages from advanced scripts

#homeScreenIcon: /public/img/my-icon-180.png

#defaultNetwork: 10.2.0.10
  
#artnet:
#  bindToAddress: 10.3.0.10
#  sendToAddress: 10.3.0.25

# Enable tftp server for network boot support.
#tftp:
#  port: 8069

This file uses the YAML file format. Lines beginning with a #-sign are comments. To activate such lines in the example above, remove the leading #-sign.

Note that the file has a hierarchical structure. For instance, the watchFiles option is nested under scripting. Options may be nested several levels deep, as is the case with the port option shown above. It is very important that you adhere precisely to this hierarchical structure, or the configuration will not work as expected. Below is a detailed description of each level of the configuration file.

When editing the configuration file, make sure you observe YAML syntax rules. In particular, indentation is significant in YAML files. Don't use tabs for indentation. Use two spaces per indentation level, as shown in the example above.

The following items are found at the top level of the configuration file.

• root. Absolute path to Blocks' root data directory. Not required when using the config.yml file inside your Blocks' root data directory (option 1 above). See more under alternative blocks data location below.
• serverRootRedirect. Server path to go to when accessing the root level of the server. This is often used to specify the path to a Visitor Spot to be accessed by default by guests using the mobile query parameter.
• defaultSpotCSS. Specifies a default CSS file that will be automatically applied to all Spots. The path must be relative (with no leading slash), and is then relative to the server's public directory. Note that this CSS file is also applied to the editor (in order to be viewed there correctly), so some care must be taken to not interfere with the editor's operation.
• homeScreenIcon. Specifies a custom home screen icon, to appear when adding a Spot to the home screen on an iOS or Android device. Specify the URL to the image file, which must be 180 x 180 pixels. Preferably, store the image on the Blocks server under /public/xxx, as shown in the example, using a URL specifying only the path to the image; e.g. "/public/img/my-icon-180.png".
• defaultNetwork. Address of network interface (NIC) to be use for general broadcast data, such as wake-on-LAN packets. Set this to the NIC used by such devices if your server has more than one active NIC, to avoid having such data go out the wrong NIC.
• scripting. The only option available hereunder is watchFiles. Set to true to automatically reload User Scripts and Devices Drivers, as those are modified. Defaults to false, requiring that you restart the server to pick up any such file changes.
• artnet. Options related to ArtNET/DMX-512 data. The bindToAddress sub-option specifies which NIC to use for Art-Net data. Set this to the IP address of the desired NIC if you want to segregate ArtNet data on a separate subnet. The sendToAddress sub-option specifies the destination address used by Art-Net data. If not specified, ArtNet data will be broadcast.
• httpClient. Options for outgoing http requests, as used by the SimpleServer scripting API. More details can be found here.
• mirror. Options for Blocks' mirroring service.
• tftp. Options for Blocks' internal TFTP-server, used for network booting of PIXILAB Player. See below.
• mail. Options for sending email from Blocks, such as the SMTP server credentials to use. See below.
• apiKeys. Keys and values for protecting Blocks API endpoints. See below.
• mqtt. Enables MQTT integration, optionally setting broker connection parameters. See below.

Some top-level items have more complex structure, and are described individually below.

This item specifies details for Blocks' web server, such as port numbers to use, where to find SSL certificates, etc.

IMPORTANT: If you specify server, you must set its type to pixilab_server, as shown above.

• type. Server type. Must be set to pixilab_server.
• corsPath and corsAllowOrigin. If you want to accept calls from other servers/clients, e.g., to endpoints specified by user scripts (using the @resource annotation), specify the root path of such requests, and the Access-Control-Allow-Origin header to be returned here.
• applicationConnectors. specifies the connection details for the web server, such as port numbers used, etc.

See below for details on server sub-options.

Specify port numbers and other server-related settings under server:applicationConnectors: like this:

server:
  type: pixilab_server
  applicationConnectors:
    - type: http
      port: 8080
      useForwardedHeaders: true

If not specified, port 8080 is used for http and https is disabled. Under Windows, you may change the http connector to use the standard port 80 instead, thus removing the need to type :8080 after domain name IP address in a browser. Under Linux/MacOS, you can not use ports below 1024.

The above example is appropriate when using PIXILAB's Linux-based server, which provides an nginx reverse proxy managing the standard HTTP port 80 by forwarding to port 8080, mentioned above. Learn more about the nginx reverse proxy, including how it can also be used to support HTTPS connection, here. The useForwardedHeaders option must be set to true when running Blocks behind a reverse proxy (and the reverse proxy must be configured to set allrelevant X-Forwarded-Xxx headers). If you're not using a reverse proxy (e.g., runnign Blocks on your Mac or Windows laptop), this setting can be omitted or set to false.

See here for more details on advanced applicationConnectors settings. Those are advanced settings, that most users won't need. PIXILAB doesn't support servers where such advanced settings have been applied.

Specifies advanced authentication and authorization options. The settings shown above correspond to the defaults if no auth section is provided. In most cases, you don't need to specify these settings. If you specify the internalForm authorization method, a "Log Out" command will be added to Blocks' Page menu, allowing you to explicitly log out. The OidcClient setting allows for integration with single-sign-on systems such as Active Directory or OKTA.

IMPORTANT: While the internalForm method provides log-out functionality, it also sends all authoriztion credentials, including your password, as clear text. The default internalDigest method, while not providing any log-out functionality, avoids sending your password as clear text. When using Blocks on publicly accessible networks, you're strongly advised to use and only allow encrypted connection#https_domain_name_and_certificate (HTTPS) for all editing operations.

Specifies options for the built-in TFTP-server. This is intended for network booting of PIXILAB Player. It accepts the following options:

tftp:
  port: 8069
  path: public/PIXILAB_Player/boot

• port is the port number used by the TFTP server. This must be specified in the configuration file to enable the TFTP-server. To use network booting of players, set this to 8069, as shown above. A firewall rule exists to redirect the standard TFTP port 69 to port 8069.
• path is the path, under the Blocks root folder, from which files will be served by the TFTP server. If not specified, this defaults to public/PIXILAB_Player/boot, as shown above, which matches the standard installation directory for the PIXILAB Player network boot files.

Specifies options used by the SimpleMailer scripting module, which can be used to send email from Blocks using user scripts. Here's an example configuration:

mail:
  sender: info@pixilab.se
  username: sendtester@pixilab.net
  password: 3522yt^$aber
  smtp.auth: true
  smtp.starttls.enable: true
  smtp.host: mail.pixilab.net
  smtp.port: 587
  smtp.ssl.trust: mail.pixilab.net
  smtp.allow8bitmime: true

• sender is the email address that will be passed along as the sender of the email.
• username is the user name given to the mail server used to send the email.
• password is the password corresponding to username, needed to send email through the mail server.

This feature relies on an external mail server. The details of that mail server are specified as additional options, and follow the Java Mail standard. Note that options specified under mail omit the leading mail. part. I.e., the option listed as mail.smtp.starttls.enable in the documentation linked to above, is specified as smtp.starttls.enable in Blocks' configuration file, since it's already under the mail heading.

The top-level logging item controls where logs are sent, and the verbosity of logs.

logging:
  # The default level of all loggers, such as OFF, ERROR, WARN, INFO
  level: WARN

  loggers:
    Realm: INFO # Log task log statements messages, regardless of originating Realm
    Script: INFO # Log "console.log" messages from advanced scripts

See here for more details on advanced logging. Those are advanced settings, that most users won't need. PIXILAB doesn't support servers where such advanced settings have been applied.

NOTE: This feature was added in Blocks 6.1. If you're using an older version, this section does not apply to you.

Lists a number of keys with their values:

apiKeys:
  upload: "super-secret" # Value required as apiKey query parameter for uploads
  customKey: "super-secret2"

The upload key's value (if specified) will be used by Blocks' file upload API. When specified, all uploads must add an apiKey query parameter to their URL, with the value specified for the upload key.

You can specify additional key/value pairs, as exemplified by the customKey key/value shown above. Such a key can then be applied to custom API endpoints decorated by @resource by also applying an @apiKey decorator, like this:

/* Receives a GET request such as:
    http://<SERVER><:PORT-IF-REQUIRED>/rest/script/invoke/ScriptName/message/on/B
   Exposing the trailing part (here "on/B") as the lastMessage property.
 */
@resource(undefined, 'GET')
@apiKey("customKey") // Requires the query parameter apiKey=super-secret2
public message(
  body: object,    // Not used for GET requests (but must still be declared!)
  trailer: string  // Trailing part of URL
) {
  this.lastMessage = trailer;
  this.resetSoon();
}

A function such as the one shown here must be placed in a User Script. For more information, see this example.

IMPORTANT: Unless you're using a secure (encrypted) server connection, apiKey query parameters are sent as clear text, and can be seen by anyone with access to your network. Learn more on how to use a secure (HTTPS) server connection here (if using our Linux based server image) or here.

NOTE: This feature was added in Blocks 6.1. If you're using an older version, this section does not apply to you.

mqtt:
  defaultBroker:
    address: localhost  # Default is localhost
    username: pixi   # Default is no username and password
    password: pixi
    encryption: false #Change to true if secure connection (tls) is available.

In the standard case, no explicit MQTT configuration is required, in which case a default broker connection to localhost with no username or password will be attempted. This is appropriate when using the MQTT broker included with our Linux server image version 221214 and later.

NOTE: In addition to an MQTT broker, a suitable device driver is required for the device you want to control (here's an example MQTT driver).

If you want to use a broker running on another computer, specify its IP address or name using the address setting as shown above. If your broker requires authorization in order to connect, you must also specify the username and password options as ecpected by your broker's configuration.

NOTE: These are the credentials of your MQTT broker – not your Blocks server.

You can store Blocks' data somewhere else than in the “PIXILAB-Blocks-root” directory in the current user's home directory. This is done by putting a file named "PIXILAB-Blocks-config.yml" in the current user's home directory (option 1 of those mentioned at the top of this article). In this case, you must specify root in the configuration file:

root: /Volume/External4/Blocks

IMPORTANT note for servers based on our Linux server image version 221214 or later: If you change the root path in the configuration file you must also change the corresponding root path under location under server in the file /etc/nginx/sites-available/blocks. You must be logged in as the pixi-admin user to edit that file and use sudo to edit the file (e.g., sudo nano /etc/nginx/sites-available/blocks), and finally restart nginx (or reboot the server).

If you're running Blocks server under Windows, the PIXILAB-Blocks-config.yml file is placed in the current user's home directory at C:\Users\[Your username]. The path to the desired Blocks root directory must be specified like this:

root: C:/External4/Blocks 

This option tells Blocks to look for its data at the specified path, thus allowing you to put Blocks' data directory where you want. Additional options are specified in this "PIXILAB-Blocks-config.yml" file, as Blocks will not look in its data directory for any config.yml file.