Mapeo Map Server

An in-progress offline map style and tile server for Mapeo.

npm install @mapeo/map-server better-sqlite3

⚠️ This is alpha software. No guarantees can be made about the stability of the API at the moment, so proceed with caution. 😄

Features

• [x] Manages tiles and tilesets (TileJSON)

• [x] Manages Mapbox map styles

• [x] Supports importing MBTile files as tilesets

  • [x] Supports getting import progress

• [ ] Provides info related to downloads and storage

Usage

The default export is a factory function for creating a map server instance, which is built on top of Fastify. Basic usage is as follows:

// better-sqlite3 is a peer dependency and must be installed manually.
const Database = require('better-sqlite3')
// If you're using TypeScript, you may want to use one of the following import syntaxes to get type definitions:
// - `require('@mapeo/map-server').default`
// - `import createMapServer from '@mapeo/map-server'
const createMapServer = require('@mapeo/map-server')

// Create the server instance
const mapServer = createMapServer(
  { logger: true },
  { data: new Database('./example.db') }
)

// Run the server!
mapServer.listen(3000, function (err) {
  if (err) {
    mapServer.log.error(err)
    process.exit(1)
  }
})

createServer(fastifyOpts, mapServerOpts): FastifyInstance

Creates the map server instance

• fastifyOpts (optional): Options object to customize the Fastify instance. Refer to the official Fastify documentation for more details.
• mapServerOpts (required): Options object to customize the map server instance. Options include:
  • database: BetterSqlite3.Database (required): BetterSqlite3 database instance representing the SQLite database to use.

API Documentation

API documentation is available in the API.md and by accessing the /docs endpoint of the server when it's running.

Technical Details

• Fastify for creating the server.
• SQLite as the underlying persistence layer.
• Prisma as a build tool for updating the schema, creating migration scripts, and generating schema assets.
  • Schema diagram can be found here.
  • Due to the distributed and local-first nature of Mapeo, migrations are performed at runtime by the server on initialization. See the migrations implementation for more details. It roughly follows the logic that Prisma uses for build-time migrations.

Developing

Some notes before working on this locally:

• If you make any changes to the schema via schema.prisma, run the following commands afterwards:
  • npm run prisma:migrate-dev -- --name MIGRATION_NAME_HERE - creates a new migration in the prisma/migrations/ directory, which is used by tests and the server if running locally

License

MIT