Installation and Operation

The following guide will walk you through the Boundless Offline Tile Server installation process, configuration options, and updating data.

Installing BOTS

BOTS does not need to be installed, in the formal sense; it is a single executable that requires very little assistance from the user. These simple steps will get BOTS up and running quickly.

  1. BOTS supports multiple operating systems. Identify the appropriate version for your system, and click the link to begin downloading.
  1. Download the appropriate version.

wget https://s3.amazonaws.com/boundless-enterprise-downloads/bots/1.0.4/bots-1.0.4-osx.zip

  1. Decompress the file.

unzip bots-1.0.4-osx.zip

  1. Verify the download.

./bots -h

You should get the following output:

-audit=true: Creates an audit (access) log at bots_audit.log
-cacheSize=200: The size of the in memory cache (in MB)
-cert="resources/test.crt": The ssl private cert
-db="": The Vectortile MBTiles Database -- multiple can be specified by separated the paths via commas
-debug=false: This flag sets the log level to debug and also causes the underlying server framework to run in debug too
-flipy=true: Some data sources will flip the Y coordinate (TMS vs XYZ) -- if tiles are appearing in strange order, flip this switch
-help=false: This message
-key="resources/test.key": The ssl private key
-logfile="": File to log output. By default we log to stdout
-loglevel="INFO": Log level - one of TRACE, DEBUG, INFO, WARN, ERROR
-port=8000: The port number
-proxy=false: For Proxies -- Whether to enable proxy settings or just use whatever hostname is found in the http request headers
-proxyhostname="localhost": For Proxies -- The hostname that should be advertised
-proxyport="8000": For Proxies -- The port that should be advertised
-proxyscheme="https": For Proxies -- The hostname that should be advertised
-ssl=true: Whether to use SSL -- disabling SSL will also disable HTTP2 -- enabled by default
-supportkey="": The entire support key
-supportkeyfile="": A file containing the support key
-uncompressedTiles=false: Set this flag if tiles aren't compressed

If you see the above message, congratulations! You are now able to run Boundless Offline Tile Server.

If you see permission denied, make sure BOTS is executable (chmod +x bots).

If you still receive the error, verify the version you’ve downloaded is right for your system.

Boundless Support is also available at support@boundlessgeo.com.

Running BOTS

This section takes you through the various switches/modifications for running BOTS. All of these options can easily be changed at the command line.

Get Help

This document contains quite a bit of information, but for a complete list of options, run bots -help.

Default Settings

To make it easy to get up and running, BOTS was created with sensible default settings. This allows BOTS to run from the command line without the need for additional options. Simply run ./bots.

BOTS will scan the local directory, look for the first available Geopackage, and attempt to serve data from it.

Once you have successfully installed BOTS, you can verify it loaded correctly by going to localhost:8000.

Support Keys

Support keys are required to run BOTS, and are embedded in the data package provided with your subscription. It will be added in transparently when the data is loaded on to the server.

Should you find this is not the case, obtain the supportkey using the following options:

  • supportkey: The entire Boundless support key provided by your sales representative or support staff.
  • supportkeyfile: The support key file provided by Boundless staff as an alternate to the above.

Data Options

  • db: A comma separated list of data files that BOTS will serve from. This will typically be sqlite, mbtiles or geopackage files. If nothing is provided, BOTS will scan the local directory looking for files.
  • cacheSize: The maximize size (in MB) of memory for BOTS to cache tiles. Caching tiles speeds up response times for subsequent requests for the same tile. The default value is 200mb.
  • flipy: Depending on how a given data package was prepared, the tile reference scheme may have a “Y” coordinate that needs to be translated. Metadata provided with the data package should indicate if this needs to be set.

Logging

  • loglevel: This controls how verbose the logging is. TRACE will record the most, and ERROR, the least. Once you are in production, WARN or ERROR should be fine. Valid options are TRACE, DEBUG, INFO, WARN, or ERROR.
  • logfile: By default, Boundless Offline Tile Server will log to stdout, which might be good for some situations. If you want to log to a specific file, add this flag to the file name: e.g. -logfile=bots.log.
  • audit: Audit is enabled by default, and logs all server access to bots_audit.log. To disable, set -audit=false.

HTTP Options

Boundless Offline Tile Server is designed to take advantage of enhancements in the HTTP 2.0 protocol, which allows servers to push data to connected clients. BOTS uses server push to preemptively send tiles to a client, which greatly enhances the client experience. Note: Server push requires HTTP2, and HTTP2 requires SSL.

We encourage you to use SSL with BOTS, not just because it’s good practice, but because it allows us to make things faster for you. However, BOTS will automatically downgrade connections back to HTTP 1.1 for any client that does not support HTTP2.

  • port: By default, Boundless Offline Tile Server will listen on port 8000. BOTS will only listen on a single port, regardless of whether or not you are using SSL. You will need to run BOTS with elevated permissions if you want to specify a port below 8000 (such as the typical HTTP ports 80 and 443).
  • ssl: Defines whether to use SSL or not. Values are “true” or “false”.
  • cert: This is the location of the SSL certificate.
  • key: This is the location of the SSL private key.

Proxies

Many servers run either behind proxies or on machines whose hostname might not resolve correctly to external clients. Boundless Offline Tile Server offers three proxy solutions for such cases. These are then used as the URLs served out by BOTS for the default viewer and style documents.

  • proxyport: The port to be advertised.
  • proxyhostname: The hostname to be advertised.
  • proxyscheme: The scheme (http or https) to be advertised.

Examples

We understand there are always multiple ways of doing things, so we’ve included several examples of how our users may want to configure Boundless Offline Tile Server.

  • Running BOTS with a simple config (verification check):

    ./bots

  • Running BOTS with a specific data package:

    ./bots -support-keyfile=test.supportkey -db=north_america.gpkg

  • Running BOTS with a data package, behind a proxy:

./bots -support-keyfile=test.supportkey -db=north_america.gpkg -proxy=true -proxyhostname=chopper.boundlessgeo.com
  • Running BOTS with a data package, behind a proxy, with SSL:
./bots -support-keyfile=test.supportkey -db=north_america.gpkg -proxy=true -proxyhostname=bots.boundlessgeo.com -cert=boundless.crt -key=boundless.key