PIXILAB Wiki

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
blocks:server_configuration_file [2023-10-24 08:02] – Added note on HTTPS for internalForm adminblocks: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/*   #corsPath: /rest/script/invoke/*
   #corsAllowOrigin: "*"   #corsAllowOrigin: "*"
-  #requireHttps: false    # Uncomment and set to false or true to control this eplicitly 
  
   applicationConnectors:   applicationConnectors:
     - type: http     - type: http
       port: 8080       port: 8080
 +      useForwardedHeaders: true  # Needed if running behind a reverse proxy
    
-  #auth:    # Uncoment to control authorization settings explicitly, defaults shown here+  #auth:    # Uncoment to control authorization settings explicitly
   #  servlet:   #  servlet:
   #    security:   #    security:
Line 83: Line 83:
   * **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 using the //mobile// [[blocks:api:query-parameters|query parameter]].   * **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 105: Line 105:
   * **type**. Server type. Must be set to //pixilab_server//.   * **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.   * **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. See below for details on server sub-options.
Line 119: Line 120:
     - type: http     - type: http
       port: 8080       port: 8080
 +      useForwardedHeaders: true
 </code> </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. 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. 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 158: Line 160:
   smtp.port: 587   smtp.port: 587
   smtp.ssl.trust: mail.pixilab.net   smtp.ssl.trust: mail.pixilab.net
 +  smtp.allow8bitmime: true
 </code> </code>
  
Line 192: Line 195:
 apiKeys: apiKeys:
   upload: "super-secret" # Value required as apiKey query parameter for uploads   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"   customKey: "super-secret2"
 </code> </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 //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: 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: