gokoala

Cloud Native OGC APIs server, written in Go

3dtiles · features · geospatial · ogc · ogcapi
入门
GitHub在线演示
Stars：46
License：MIT License
更新：2025/12/19

README

GoKoala

GoKoala

Cloud Native OGC APIs server, written in Go.

Build Lint (go) Lint (ts) Go Report Card Coverage (go) GitHub license Docker Pulls

Description

This server implements modern OGC APIs such as Common, Tiles, Styles, Features and GeoVolumes in a cloud-native way. It contains a complete implementation of OGC API Features (part 1, 2 and 5). With respect to OGC API Tiles, Styles, GeoVolumes the goal is to keep a narrow focus, meaning complex logic is delegated to other implementations. For example, vector tile hosting may be delegated to a vector tile engine, 3D tile hosting to object storage, raster map hosting to a WMS server, etc.

This application is deliberately not multi-tenant, it exposes an OGC API for one dataset. Want to host multiple datasets? Spin up a separate instance/container.

Demo

See OGC APIs listed on https://api.pdok.nl. These are powered by GoKoala.

Features

  • OGC API Common serves landing page and conformance declaration. Also serves OpenAPI specification and interactive Swagger UI. Multilingual support available.
  • OGC API Features supports Part 1 (core), Part 2 (crs) and Part 5 (schema) of the spec.
    • Serves features as HTML, GeoJSON and JSON-FG.
    • Supported datastores:
      • GeoPackage. These can be regular/local or Cloud-Backed GeoPackages. No on-the-fly reprojection/transformation is applied, separate GeoPackages should be configured ahead-of-time in each CRS.
      • PostgreSQL (PostGIS). Supports on-the-fly reprojection/transformation of features.
    • Supports property filtering (/items?<property>=<value>) and temporal filtering (/items?datetime=<timestamp>).
    • Implements cursor-based pagination (also known as keyset pagination) to support browsing large datasets.
    • Offers the ability to serve features representing "map sheets", allowing users to download a certain geographic area in an arbitrary format like zip, gpkg, etc.
    • Validates required indexes on startup.
  • OGC API Tiles serves HTML, JSON and TileJSON metadata. Act as a proxy in front of a vector tiles server (like Trex, Tegola, Martin) or object storage of your choosing. Currently, three projections (RD, ETRS89 and WebMercator) are supported. Both dataset tiles and geodata tiles (= tiles per collection) are supported.
  • OGC API Styles serves HTML (including legends) and JSON representation of supported (Mapbox) styles.
  • OGC API 3D GeoVolumes serves HTML and JSON metadata and functions as a proxy in front of a 3D Tiles server/storage of your choosing.

Build

docker build -t pdok/gokoala .

Run

NAME:
   GoKoala - Cloud Native OGC APIs server, written in Go

USAGE:
   GoKoala [global options] command [command options] [arguments...]

COMMANDS:
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --host value            bind host for OGC server (default: "0.0.0.0") [$HOST]
   --port value            bind port for OGC server (default: 8080) [$PORT]
   --debug-port value      bind port for debug server (disabled by default), do not expose this port publicly (default: -1) [$DEBUG_PORT]
   --shutdown-delay value  delay (in seconds) before initiating graceful shutdown (e.g. useful in k8s to allow ingress controller to update their endpoints list) (default: 0) [$SHUTDOWN_DELAY]
   --config-file value     reference to YAML configuration file [$CONFIG_FILE]
   --theme-file value      reference to a (customized) YAML configuration file for the theme [$THEME_FILE]
   --openapi-file value    reference to a (customized) OGC OpenAPI spec for the dynamic parts of your OGC API [$OPENAPI_FILE]
   --enable-trailing-slash allow API calls to URLs with a trailing slash. (default: false) [$ALLOW_TRAILING_SLASH]
   --enable-cors           enable Cross-Origin Resource Sharing (CORS) as required by OGC API specs. Disable if you handle CORS elsewhere. (default: false) [$ENABLE_CORS]
   --help, -h              show help

Example (config-file is mandatory):

docker run -v `pwd`/examples:/examples -p 8080:8080 -it pdok/gokoala --config-file /examples/config_vectortiles.yaml

Now open http://localhost:8080. See examples for more details.

Configuration file

The configuration file consists of a general section and a section per OGC API building block (tiles, styles, etc). See example configuration files for details. You can reference environment variables in the configuration file. For example to use the MY_SERVER env var:

ogcApi:
  tiles:
    title: My Dataset
    tileServer: https://${MY_SERVER}/foo/bar

Custom theming

GoKoala offers some minimal theming options. When running GoKoala, pass an argument of -theme-file to load a custom theming file. The theme.yaml contains the configurable options (colors, images, extra HTML) for the theme.

For example:

  • Create a directory e.g. mytheme and place a customized copy of theme.yaml and additional assets/images in this directory.
  • Mount mytheme as a volume and start GoKoala with the custom theme:
docker run -v `pwd`/examples:/examples -v `pwd`/mytheme:/mytheme -p 8080:8080 -it pdok/gokoala \
 --config-file /examples/config_vectortiles.yaml --theme-file /mytheme/theme.yaml

GeoPackage requirements

GoKoala has a few requirements regarding GeoPackages backing an OGC API Features:

  • Feature IDs (fid) in the GeoPackage should be auto-incrementing.
  • Each column used for property filtering should have an index, unless indexRequired: false is specified in the config.
  • Each feature table must contain a RTree index.
  • Each feature table must contain a BTree spatial index:
select load_extension('/path/to/mod_spatialite');
alter table "<table>" add minx numeric;
alter table "<table>" add maxx numeric;
alter table "<table>" add miny numeric;
alter table "<table>" add maxy numeric;
update "<table>" set minx = st_minx('geom'), maxx = st_maxx('geom'), miny = st_miny('geom'), maxy = st_maxy('geom');
create index "<table>_spatial_idx" on "<table>"(fid, minx, maxx, miny, maxy);
  • When enabling temporal filtering (using datetime query param) the temporal fields should be indexed and the spatial index should be expanded to include the temporal fields.
create index "<table>_spatial_idx" on "<table>"(fid, minx, maxx, miny, maxy, start_date, end_date);
create index "<table>_temporal_idx" on "<table>"(start_date, end_date);

This is in addition to some of the requirements set forth by the PDOK GeoPackage validator. Some of the requirements stated above can be automatically applied with help of the PDOK GeoPackage optimizer.

When using Cloud-Backed GeoPackages we recommend a local cache that is able to hold the spatial index, see maxSize in the config.

PostgreSQL requirements

Likewise, GoKoala has a few requirements regarding PostgreSQL backing an OGC API Features:

  • Feature IDs (fid) in the table should be auto-incrementing.
  • Each column used for property filtering should have an index, unless indexRequired: false is specified in the config.
  • PostGIS extension needs to be installed and enabled.
  • The geometry field in the table must contain a GIST index.
  • When enabling temporal filtering (using datetime query param) the temporal fields should be indexed:
create index "<table>_temporal_idx" on "<table>" (start_date, end_date);

Feature schema

GoKoala supports OGC API Features part 5 (schemas). The schema for each collection is automatically derived from the underlying - Geopackage or PostgreSQL - table. Optionally, one can enrich the schema with field/property descriptions.

When using GeoPackages you'll need to add the GeoPackage schema extension. This includes adding a gpkg_data_columns table and inserting a description for each field.

When using PostgreSQL you can add a comment on each column. This comment will be used as the field description. For example:

comment on column <table>.<field> is "Some description about this field for the end-user";

OpenAPI spec

GoKoala ships with OGC OpenAPI support out of the box, see OpenAPI specs for details. You can overwrite or extend the defaults by providing your own spec using the openapi-file CLI flag.

Observability

Health checks

Health endpoint is available on /health. When the server is configured to serve OGC API Tiles, the health endpoint will check for the presence of a specific tile on the configured tileserver. When no OGC API Tiles are configured, the health endpoint will simply serve an HTTP 200 when called.

By default, when OGC API Tiles are configured, the checked tile is determined from a fixed lookup table, based on the deepest zoomlevel (i.e., zoomLevelRange.end) of EPSG:28992 (e.g., if the deepest zoomlevel is 12, the path of the checked tile is /NetherlandsRDNewQuad/12/1462/2288.pbf).
It is possible to override the tile to be checked, both in terms of projection (SRS/CRS) and specific tile path:

ogcApi:
  tiles:
    healthCheck:
      srs: EPSG:3035
      tilePath: /EuropeanETRS89_LAEAQuad/14/8237/7303

When specifying a projection other than EPSG:28992, the tilePath must also be specified. When specifying a tilePath, the format to be used is either /{tileMatrixSetId}/{tileMatrix}/{col}/{row}.pbf or /{tileMatrixSetId}/{tileMatrix}/{row}/{col}.pbf (depending on what order the tile server requires).

Profiling

Besides the main OGC server GoKoala can also start a debug server. This server binds to localhost and a different port which you must specify using the --debug-port flag. You shouldn't expose this port publicly but only access it through a tunnel/port-forward. The debug server exposes /debug for use by pprof. For example with --debug-port 9001:

  • Create a tunnel to the debug server e.g., in k8s: kubectl port-forward gokoala-75f59d57f4-4nd6q 9001:9001
  • Capture CPU profile: go tool pprof http://localhost:9001/debug/pprof/profile?seconds=20
  • Capture Memory profile: go tool pprof http://localhost:9001/debug/pprof/heap?seconds=20
  • Start pprof visualization go tool pprof -http=":8000" pprofbin <path to pb.gz file>
  • Open http://localhost:8000 to explore CPU flamegraphs or Heap details.

SQL query logging

Set LOG_SQL=true environment variable to enable logging of all SQL queries to stdout for debug purposes. Only applies to OGC API Features with GeoPackage and/or PostgreSQL data source.

Develop

Design principles:

  • Performance and scalability are key!
  • Be opinionated when you can, only make stuff configurable when you must.
  • Fail fast, fail hard: do as much pre-processing/validation on startup instead of during request handling.
  • The ogc package contains logic per specific OGC API building block.
  • The engine package should contain general logic. ogc may reference engine.

    :warning: The other way around is not allowed!

  • Document public APIs with godoc
  • Geospatial related configuration is done through the config file, technical configuration (host/port/etc) is done through CLI flags/env variables.
  • Assets/templates/etc should be explicitly included in the Docker image, see COPY commands in Dockerfile.

Build/run as Go application

Make sure SpatiaLite, PROJ, openssl and curl are installed. Also make sure gcc or similar is available since the application uses cgo.

go build -o gokoala cmd/main.go
./gokoala

To troubleshoot, review the Dockerfile since compilation also happens there. Optionally set SPATIALITE_LIBRARY_PATH=/path/to/spatialite when SpatiaLite isn't found.

Testing

To run all unit tests:

go test -v -race -shuffle=on ./...

Optionally set SPATIALITE_LIBRARY_PATH=/path/to/spatialite when SpatiaLite isn't found. Some tests make use of Testcontainers so you'll need to have Docker installed.

Linting

Install golangci-lint and run golangci-lint run ./... from the root.

Viewer

GoKoala includes a viewer which is available as a set of Web Components for embedding in HTML pages. To use the viewer locally when running GoKoala outside Docker execute: hack/build-local-viewer.sh. This will build the viewer and add it to the GoKoala assets.

Note this is only required for local development. When running GoKoala in a container this is already being taken care of when building the Docker container image.

IntelliJ / GoLand

  • Install the Go Template plugin
  • Open Preferences > Editor > File Types select Go Template files and add the following file patterns:
    • "*.go.html"
    • "*.go.json"
    • "*.go.tilejson"
    • "*.go.xml"
  • Now add template language support by running the setup-jetbrains-gotemplates.sh script.
  • Reopen the project (or restart IDE). Now you'll have full IDE support in the GoKoala templates.

Also:

  • Set import order in Preferences > Editor > Code Style > Go > Imports to goimports to align with VSCode and goimports usage in golangci-lint.

VSCode

  • Install the Go Template extension
  • Open Extension Settings and add the following file patterns:
    • "*.go.html"
    • "*.go.json"
    • "*.go.tilejson"
    • "*.go.xml"
  • Also add html, json and xml to the list of Go template languages.
  • Now you'll have IDE support in the GoKoala templates.

OGC compliance validation

See our end-to-end tests for details.

Misc

How to Contribute

Make a pull request...

Contact

Contacting the maintainers can be done through the issue tracker.