PIXILAB Wiki

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
blocks:server_configuration_file [2023-04-24 08:18]
admin Added HTTPS note to apiKeys item 		blocks:server_configuration_file [2024-05-17 07:41] (current)
admin defaultSpotCSS added note
Line 33: Line 33:
   #corsPath: /rest/script/invoke/*   #corsPath: /rest/script/invoke/*
   #corsAllowOrigin: "*"   #corsAllowOrigin: "*"
 +
   applicationConnectors:   applicationConnectors:
     - type: http     - type: http
       port: 8080       port: 8080
-      +  
 +  #auth:    # Uncoment to control authorization settings explicitly 
 +  #  servlet: 
 +  #    security: 
 +  #      - matchers: internalMatcher 
 +  #        authorizers: isAuthenticated 
 +  #        clients: internalDigest  # internalDigest internalForm OidcClient 
 +     
 scripting: scripting:
   watchFiles: true   watchFiles: true
Line 73: Line 81:
  
   * **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.   * **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".   * **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.   * **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 92:
   * **mail**. Options for sending email from Blocks, such as the SMTP server credentials to use. 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.   * **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. Some top-level items have more complex structure, and are described individually below.
Line 120: Line 129:
 === server: auth === === 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 ==== ==== 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: 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 193: Line 204:
  */  */
 @resource(undefined, 'GET') @resource(undefined, 'GET')
-@apiKey("simpleHttpKey")+@apiKey("customKey") // Requires the query parameter apiKey=super-secret2
 public message( public message(
   body: object,    // Not used for GET requests (but must still be declared!)   body: object,    // Not used for GET requests (but must still be declared!)
Line 206: Line 217:
  
 :!: **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]]. :!: **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 ===== ===== Alternative Blocks Root Directory =====