Deployment Guide

Build

Our builds zip up the contents of the dist folder after yarn run build completes. This results in a zip directory structure like:

{appName}/
  config/
    settings.json
  v{buildtime}/
    ... code
  index.html

Generally, this build does not include any deployment-specific config. Since we have multiple deployments, and we do not wish to run the (much longer) full build for each separate deployment, we have other build jobs which grab the settings.json file out of this zip, merge in the deployment-specific config, and save it as {app}-{version}-{deployment}.zip. However, if you only have a single deployment, you may wish to include your deployment config as a config project during the main build.

Settings

See our Settings Guide to get familiar with the main settings to configure for your deployment, such as remote servers and base map layers.

HTTP Server

We highly recommend the use of nginx to serve the application. However, since the application is entirely static html, js, css, etc. it can be served with any HTTP server. The following config examples will be using nginx.

Define the WASM type

Our build includes some *.wasm files. Browsers complain in the console if the mime type is not set properly for these.

http {
  ...

  include mime.types;
  types {
    application/wasm wasm;
  }
}

Enable GZIP

This should go without saying. Nevertheless:

 http {
   ...

   gzip on;
   gzip_disable "msie6";
   gzip_min_length 1100;
   gzip_vary on;
   gzip_buffers 16 8k;
   gzip static always;
   gzip_types text/plain text/css text/js text/xml text/html text/javascript application/javascript application/x-javascript application/json application/xml application/xml+rss application/wasm;
}

Caching

We should allow the browser to cache config for a couple of hours and the version folder (v{buildtime}) for as long as possible.

http {
  ...
  server {
    ...
    # allow clients to cache config for a couple of hours
    location ^~ /opensphere/config/ {
      add_header 'Cache-Control' 'max-age=7200, public' always;
    }

    # anything under the version directories should be cached for the maximum (one year)
    location ^~ /opensphere/v\d+/ {
      add_header 'Cache-Control' 'max-age=31557600, public' always;
    }
  }
}

Note

If you dropped the app name (such that the application is available directly on yourdomain.com/ rather than yourdomain.com/opensphere), you will need to drop the /opensphere off the location directives in the above example.

Deploying

The directory structure is designed to simply be unzipped over old installs. This allows users with cached index.html pages to previous versions to work until they request index.html again after that cache expires (generally 20-30 minutes). Therefore, just cd to the document root and unzip the file (and ensure that permissions are set correctly for your server, of course).

API Keys

Some data or search providers require an API Key to function. For development, you can merely drop the API Key directly in config:

Warning

The following is acceptable for dev config but should not be done in production! Anyone who uses the application will have access to the API Key.

{
  "admin": {
    "plugin": {
      "myplugin": {
        "url": "https://api.somecoolsite.com/search?q={q}&api_key=SOMETHING"
      }
    }
  }
}

For production, it is better to hide that API behind a proxy that you control.

http {
  ...
  server {
    ...
    location /somecoolsite/search {
      set $args $args&api_key=SOMETHING;
      proxy_pass https://api.somecoolsite.com/search;
    }
  }
}

And the production config:

{
  "admin": {
    "plugin": {
      "myplugin": {
        "url": "/somecoolsite/search?q={q}"
      }
    }
  }
}