Mapboard GIS

Tethering to PostGIS

Working with large datasets in PostGIS

In Tethered mode, Mapboard GIS can turn over all spatial processing functionality to a centralized PostGIS database. PostGIS is an extremely popular and widespread open-source spatial database system that can be used within most modern GIS applications.

With its server extensions, Mapboard GIS can connect to a PostGIS database alongside desktop GIS software.

Offloading spatial operations to a server-side database has several advantages:

  • It enables work against much larger datasets than an iPad can handle locally.
  • It allows real-time interoperability with other GIS systems (e.g. drawing in Mapboard GIS can be paired with data cleaning in QGIS)
  • It allows collaborative mapping, with multiple iPads tethered to the same spatial database.

The core spatial server

Topological functions are not required for a basic connection to PostGIS. In its simplest form, Tethered mode requires a connection to a networked server running Mapboard's server extensions, or another server implementing the same external interface.

This server relies on a simple schema of four spatial tables within a PostGIS database: linework, linework_type, polygon, and polygon_type. These are the same core tables that drive the Spatialite backend (see file format docs). These tables can be housed in any schema, but we use map_digitizer by default.


The correspondence between PostGIS and Spatialite table structure will eventually be expanded to drive "hybrid" workflows with managed syncing from offline mapping back into a broader project.

PostGIS with managed topology

The most robust way to run a fully featured mapping server for work with Mapboard GIS is to use the PostGIS Geologic Map topology watcher. This software manages the topology of a geologic map iteratively, independent of the choice of GIS platform for making edits.

PostGIS Geologic Map enables iterative topological solving against the server-side data store for Mapboard GIS data.

PostGIS Geologic Map is designed to be testable, validated, and performant, and it serves as the basis for advanced topological operations within Mapboard GIS. Although the solver is agnostic to input GIS environment, the Mapboard server extensions are bundled by default.

Command-line output of the PostGIS Geologic Map topology solver (geologic-map serve)

PostGIS Geologic Map adds to the map_digitizer schema that tracks core map edits with a map_topology schema that organizes the solved topological relationships that make up the map. This schema can be regenerated at will, but progressively updating its tables serves as the basis for the iterative map editing showcased in Mapboard GIS.


The algorithms that drive PostGIS Geologic Map are a key component of a draft manuscript that discusses the new methodology being developed here. Updates will come soon!

Installing the server components

Since both PostGIS Geologic Map (preferred) and the core Mapboard server extensions are server-side software, installing and connecting to them can be difficult. Both projects can be built from source by downloading the code from GitHub. Both can be installed locally or using Docker to manage the containerized app, including the requisite database server.

For PostGIS Geologic Map, the preferred server implementation, installation is well-covered in the README. The gist of creating a Docker-managed build (with test data) is as follows:

  1. Make sure Docker and docker-compose are installed using the instructions for your platform.
  2. Modify the docker-assets/docker-map-config.json configuration file to suit your needs (typically, this involves changing the srid and tolerance fields). A better way to configure the application in Docker is forthcoming.
  3. Run docker-compose up --build. No need for a local PostgreSQL installation!
  4. Connect to the geologic_map database on local port 54321 using your GIS software or database client.
  "app": "mapboard-server",
  "version": "2.0.0",
  "projection": {
    "srid": 32733,
    "auth": "EPSG:32733",
    "description": "WGS 84 / UTM zone 33S",
    "projected": true,
    "proj4": "+proj=utm +zone=33 +south +datum=WGS84 +units=m +no_defs "
  "topology": {
    "name": "map_topology",
    "srid": 32733,
    "precision": 0.1
  "backend": "PostGIS",
  "capabilities": [
The REST server response from a successful /meta request

Once you've started the application, the Mapboard server should be running locally on your computer. By default, the server is exposed on port 3006. You can verify this by navigating to http://localhost:3006/meta in your browser. You should see a REST API response much like the one below:

This means you've successfully installed the Mapboard server! If you're using the server without the PostGIS Geologic Map extensions, the capabilities array will contain fewer entries. This tells Mapboard GIS to disable the corresponding functionality.


The next step is connecting to the server from Mapboard GIS. If you are running the application on a publicly addressable machine, the server will be available at <your-server-address>:3006. Otherwise you have to find your IP address or local network address. On MacOS this is done in the Sharing panel of System Preferences. Alternatively, the raw IP address can be found using the command ipconfig getifaddr en0 (on Mac and Linux platforms). Windows users, you're on your own for now, sorry!

The local network address for my machine is Daven-Quinn.local. This is an alias for IP address, which changes as my local router allocates IP addresses.
Entering the server information into the Project edit panel

Once you have the proper connection string (e.g., Daven-Quinn.local:3006), you can connect in Mapboard GIS at the project creation/editing interface. When the project is loaded, the app will begin talking to the server at that address to load linework and handle editing.