Skip to content

How to run basemaps locally

This guide shows you how to set up and run a local instance of the basemaps system on your machine. This guide explains how to:

  • build the basemaps packages
  • configure and run the basemaps/server package:
    • using LINZ's imagery
    • using your own imagery

Note

If you're planning to contribute to the basemaps repository, make sure you review the CONTRIBUTING document beforehand.

Prerequisites

NodeJS

You'll need Node.js version 18 or higher to build the basemaps packages.

Tip

You can use tools like fnm or n to manage Node.js versions on your machine.

Imagery

You'll need AWS credentials with permission to read files from the LINZ AWS S3 bucket at s3://linz-basemaps. Such credentials are needed to access or generate the config file required to run the basemaps system using LINZ's imagery.

You'll need a collection of GeoTIFF files organised in any way you prefer. The collection must maintain a consistent resolution and spatial reference throughout. The basemaps system is only compatible with datasets with a uniform ground sampling distance and map projection.

Get started

Clone the linz/basemaps repository to your machine.

git clone https://github.com/linz/basemaps.git

git clone git@github.com:linz/basemaps.git

gh repo clone linz/basemaps

Path

This guide uses variables as shorthand to reference key directories and files. On your machine, consider the following path:

The path to the basemaps repository folder on your machine.

$BM_REPO = {path_to}/basemaps

Build the basemaps packages

In a terminal, navigate to BM_REPO and run the following commands:

# Install the Node.js dependencies for the system
npm install

# Generate the <package_name>/build for each package
npm run build

# Run the unit tests for each package
npm run test

Tip

You can build the basemaps packages in watch mode so that they recompile anytime you modify the source code. In a terminal, navigate to BM_REPO and run the following command:

# Generate the <package_name>/build for each package (watch mode)
npm run build -- --watch

Configure the basemaps/server package

There are two main ways you can configure and run the basemaps/server package:

Serve basemaps using a bundled config file

Serve basemaps using a collection of GeoTIFF files