Differences

This shows you the differences between two versions of the page.

--- blocks:server_configuration_file [2023-04-24 08:20] – typo admin
+++ blocks:server_configuration_file [2025-11-12 09:13] (current) – Note for spotSnap added in 7.4 admin
@@ Line 33: / Line 33: @@
   #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
@@ Line 73: / Line 82: @@
   * **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|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.
+  * **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// [[blocks:api:query-parameters|query parameter]].
-  * **defaultSpotCSS**. Specifies a default CSS file that will be automatically applied to all Spots. The path, if any, must be specified relative to the public directory.
+  * **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.
@@ Line 84: / Line 93: @@
   * **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.
@@ Line 95: / Line 105: @@
   * **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 [[https://github.com/pixilab/blocks-script/blob/master/system_lib/Metadata.ts#L136|@resource annotation]]), specify the root path of such requests, and the [[https://stackoverflow.com/questions/10636611/how-does-access-control-allow-origin-header-work|Access-Control-Allow-Origin]] header to be returned here.
-  * ** applicationConnectors**. specifies the connection details for the web server, such as port numbers used, etc.
+  * ** applicationConnectors**. Specifies the connection details for the web server, such as port numbers used, etc.
+  * **allowCrossSiteAuth**. Set to true to allow cross-site authentication (e.g. for the Blocks editor), such as from within an IFRAME. Browsers allow this only under HTTPS, so you'll need HTTPS and a certificate to use this feature in addition to setting this option to true.
 See below for details on server sub-options.
@@ Line 109: / Line 120: @@
     - type: http
       port: 8080
+      useForwardedHeaders: true
 </code>
 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, [[blocks:server:nginx|here]].
+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, [[blocks:server:nginx|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 [[https://www.dropwizard.io/en/latest/manual/configuration.html#man-configuration-connectors|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.
@@ Line 120: / Line 132: @@
 === server: auth ===
-Specifies advanced authentication and authorization options. In most cases, you don't need to specify these settings. Use only when specifically instructed to do so, e.g. for integration with single-sign-on systems such as [[blocks:sso:adfs|Active Directory]] or [[blocks:sso:okta|OKTA]].
+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 [[blocks:sso:adfs|Active Directory]] or [[blocks:sso:okta|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 [[blocks:server:nginx|encrypted connection#https_domain_name_and_certificate]] (HTTPS) for all editing operations.
 ==== Top level tftp item ====
 Specifies options for the built-in TFTP-server. This is intended for [[blocks:server:pxe-boot|network booting]] of PIXILAB Player. It accepts the following options:
@@ Line 146: / Line 160: @@
   smtp.port: 587
   smtp.ssl.trust: mail.pixilab.net
+  smtp.allow8bitmime: true
 </code>
@@ Line 180: / Line 195: @@
 apiKeys:
   upload: "super-secret" # Value required as apiKey query parameter for uploads
+  spotSnap: "spot-screen-spy" # Value required as apiKey for viewing screenshots
   customKey: "super-secret2"
 </code>
 The //upload// key's value (if specified) will be used by Blocks' [[blocks:api:upload|file upload API]]. When specified, all uploads must add an //apiKey// query parameter to their URL, with the value specified for the //upload// key.
+The //spotSnap// key's value (if specified) will allow Blocks' [[blocks:api:spot-screenshot|Display Spot Screenshot API]] to be used from non-authenticated clients. This setting was added in Blocks 7.4.
 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:
@@ Line 206: / Line 224: @@
 :!: **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 [[blocks:server:nginx|here (if using our Linux based server image)]] or [[blocks:server:https|here]].
+==== Top level mqtt item ====
+:!: **NOTE**: This feature was added in Blocks 6.1. If you're using an older version, this section does not apply to you.
+<code>
+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.
+</code>
+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 [[blocks:server:advanced_server_configuration:mqtt|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 [[https://github.com/pixilab/blocks-script/blob/6.1/driver-archive/ShellySwitchGen1.ts|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 [[blocks:server:advanced_server_configuration:mqtt#security|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.
 ===== Alternative Blocks Root Directory =====