Using servers.json to Configure Immerse Options

This topic describes how to use the servers.json file to define the default connection behavior in MapD Immerse. It describes how to enable default behavior using servers.json, provides basic syntax, and includes examples. You can define the MapD database to connect to, as well as the username and password. You can also configure Immerse to use additional tile sources for geo charts.

Editing mapd.conf to Enable servers.json
servers.json File Properties
Configuring Data Source and User Login Credentials
Enable Custom Styles
Enable Custom Basemap Styles for Geo Charts

Editing mapd.conf to Enable servers.json

To enable default behavior through a servers.json file, you must first edit mapd.conf to include servers.json information:

In your MAPD_STORAGE directory, open mapd.conf. For information about mapd.conf and available options, see Configuration.
In the [web] section of mapd.conf, reference servers.json by adding the following line:

servers-json = "<MAPD_STORAGE>/servers.json"

Replace <MAPD_STORAGE> with the full path to servers.json.

Save mapd.conf.

servers.json File Properties

Property	Description
`"database": "<database_name>"`	The name of the database that Immerse connects to by default.
`"username": "<username>"`	Name of the Immerse user.
`"password": "<password>"`	Immerse user password.
`"port": "<port_number>"`	Port used for connecting to the database host.
`"host": "<hostname>"`	Name of the database host.
`"protocol": "<protocol>"`	Connection protocol to use: `http` or `https`.
`"url": "<URL>"`	Universal resource locator. Defines the path to the source database. Can be used as an alternative to identifying host and protocol.
`"customStyles": "<[options]>"`	Productize Immerse by customizing colors, login text, logo, and other UI elements. For more information, see Enable Custom Styles.
`"mapboxCustomStyles": "<[options]>"`	Specify and use basemap styles other than those provided with Immerse. For more information, see Enable Custom Basemap Styles for Geo Charts.

Note: To connect to the database, Immerse currently uses the protocol that is used to load Immerse, regardless of the protocol specified in url or protocol.

Configuring Data Source and User Login Credentials

You can create a servers.json file to control the default configuration when you log in to MapD Immerse. The information in servers.json can identify the database you connect to and credentials to use during automatic login.

If servers.json does not exist yet, create a file by that name in the MAPD_STORAGE directory.
In servers.json, specify the database to connect to, as well as username and password information. You can use host, port, and protocol to specify the path to the data:

[
   {
          "database": "<database_name>",
          "port": "<port_number>",
          "host": "<hostname>",
          "protocol": "<protocol>",
          "username": "<username>",
          "password": "<password>"
        }
]

Alternatively, you can define the data source using a URL:

[
   {
          "database": "<database_name>",
          "url": "<URL>",
          "username": "<username>",
          "password": "<password>"
        }
]

Save servers.json.

Note: If you leave the option values blank, the Immerse login form loads with blank fields.

Enable Custom Styles

To productize MapD Immerse, you can add the customStyles JSON object to servers.json. Use the customStyles elements to:

Customize colors
Customize the text displayed in the browser tab
Add your own logo
Customize the login text
Disable the Help menu dropdown on the navigation bar

JSON Branding Elements
Element	Description
`buttonPrimaryColor`	Button color when inactive
`buttonSecondaryHighlightColor`	Button color when hovering.
`colors`	Hexadecimal color definitions used in charts.
`custom`	Custom colors, requires 11 or more colors.
`disableHelpMenu`	Set to `true` to disable Help dropdown on the navigation bar.
`loginText`	Specify custom text for the Immerse login page.
`logoURL`	URL to your logo. This must be a browser-accessible http(s) URL, not a file system path.
`ordinal`	4 scales, 1 or more colors each scale.
`quantitative`	4 scales, 1 or more colors each scale.
`secondaryButtonColor`	Button color when pressed.
`solid`	Solid colors, requires 8 or more colors.
`title`	Text displayed in the browser tab.

Note

There are no visual design guarantees when using a large number of colors. For example, visual elements might bleed beyond borders or have an unexpected layout.
Custom styles do not affect the settings for charts or dashboards saved before the custom styles are defined. However, you can edit existing charts and replace the colors in use to colors in your custom palette.

Example

Create your customStyles settings as an array in your servers.json file.

[
   {
     "customStyles": {
        "logoURL": "https://media.tickleknucklebee.com/pictures/pitchers/pitcher.jpg",
        "loginText": "Log in to TickleKnuckleBee",
        "buttonPrimaryColor": "#E5BC2C",
        "buttonSecondaryColor": "#4D88B4",
        "buttonSecondaryHighlightColor": "#4D88B4",
        "colors": {
          "solid": [
             "#ce006f",
             "#b50061",
             "#9b0053",
             "#8a004a",
             "#7b003a",
             "#ffb370",
             "#fc9e4a",
             "#ff8f2a"
          ],
          "custom": [
             "#ce006f",
             "#b50061",
             "#9b0053",
             "#8a004a",
             "#7b003a",
             "#ffb370",
             "#fc9e4a",
             "#ff8f2a",
             "#fc8113",
             "#ff7800",
             "#ff7800"
          ],
          "ordinal": [
             [
                "#2F1510",
                "#ECFE71"
             ],
             [
                "#2F1510",
                "#665A79",
                "#C7F779"
             ],
             [
                "#2F1510",
                "#5D3546",
                "#5B7797",
                "#39BFA9",
                "#ECFE71"
             ],
             [
                "#2F1510",
                "#492328",
                "#5D3546",
                "#674C68",
                "#626889",
                "#5086A2",
                "#36A3AD",
                "#39BFA9",
                "#67D99A",
                "#A5EE84",
                "#ECFE71"
             ]
          ],
          "quantitative": [
             [
                "#2F1510",
                "#3D1B1B",
                "#492328",
                "#542B36",
                "#5D3546",
                "#644057",
                "#674C68",
                "#665A79",
                "#626889",
                "#5B7797",
                "#5086A2",
                "#4395A9",
                "#36A3AD",
                "#31B2AD",
                "#39BFA9",
                "#4CCCA3",
                "#67D99A",
                "#84E48F",
                "#A5EE84",
                "#C7F779",
                "#ECFE71"
             ],
             [
              "#2F1510",
              "#ECFE71"
             ],
             [
                "#FF3030",
                "#FF8000",
                "#FFF68F"
             ],
             [
              "#9bb0ff",
              "#e0e5ff",
              "#ffc38b"
             ]
          ]
        }
     }
   }
]

Enable Custom Basemap Styles for Geo Charts

If you work extensively with geospatial data, you might need to use basemap styles that are different than those provided by Immerse. By modifying servers.json, you can use custom map styles created with Mapbox Studio, as well as third-party OGC-compliant raster tile sources.

To use different basemap styles, add the mapboxCustomStyles property, and then define the source.

Note: Entering a source incorrectly can result in unexpected behavior in the geo charts, or cause Immerse to not load. Make sure that mapboxCustomStyles is an array, and that the objects in the array have label and value properties. To avoid errors, consider using a JSON validator like JSON Lint to make sure the code is correctly formatted before starting Immerse.

The following example syntax shows how to add custom base maps using the mapboxCustomStyles property, in the following order:

A custom map style created in Mapbox Studio and hosted on mapbox.com.
A basemap style hosted on a Mapbox Atlas Server.
A third-party OGC-compliant raster tiles source not affiliated with Mapbox. This source must adhere to the Mapbox Style Specification.

[
  {
        "database": "<database>",
        "password": "<password>",
        "url": "<mapdserver>",
        "port": "<port_number>",
        "username": "<username>",
        "mapboxCustomStyles": [
          {
                "label": "custom-mapbox-studio-source",
                "value": "mapbox://styles/mapd/<mapbox-studio-style-id>"
          },
          {
                "label": "mapbox-atlas-source",
                "value": "http://<domain>:<port>/pages/<style_name>/<style_name>.json"
          },
          {
                "label": "3rd-party-raster-source",
                "value": {
                  "version": 8,
                  "sources": {
                          "openstreetmap": {
                                  "type": "raster",
                                  "tiles": [
                                          "http://a.tile.openstreetmap.org/{z}/{x}/{y}.png",
                                          "http://b.tile.openstreetmap.org/{z}/{x}/{y}.png"
                                  ],
                                  "tileSize": 256
                          }
                  },
                  "layers": [{
                          "id": "openstreetmap",
                          "type": "raster",
                          "source": "openstreetmap",
                          "minzoom": 0,
                          "maxzoom": 22
                  }]
                }
          }
        ]
  }
]