/pg_featureserv

Lightweight RESTful Geospatial Feature Server for PostGIS in Go

Primary LanguageGoApache License 2.0Apache-2.0

pg_featureserv

.github/workflows/ci.yml

A lightweight RESTful geospatial feature server for PostGIS, written in Go. It supports the OGC API - Features REST API standard.

See also our companion project pg_tileserv.

Features

  • Implements the OGC API - Features standard.
    • Standard query parameters: limit, bbox, bbox-crs, property filtering, sortby, crs
    • Query parameters filter and filter-crs allow CQL filtering, with spatial support
    • Extended query parameters: offset, properties, transform, precision, groupby
  • Data responses are formatted in JSON and GeoJSON
  • Provides a simple HTML user interface, with web maps to view spatial data
  • Uses the power of PostgreSQL to reduce the amount of code and to make data definition easy and familiar.
    • Feature collections are defined by database objects (tables and views)
    • Filters are executed in the database, and use indexes where defined
  • Uses PostGIS to provide geospatial functionality:
    • Spatial filtering
    • Transforming geometry data into the output coordinate system
    • Marshalling feature data into GeoJSON
  • Full-featured HTTP support
    • CORS support with configurable Allowed Origins
    • GZIP response encoding
    • HTTP and HTTPS support

For a full list of software capabilities see FEATURES.

Documentation

Relevant Standards

Download

Builds of the latest code:

Build from Source

pg_featureserv is developed under Go 1.13. It may also work with earlier versions.

  • Ensure the Go compiler is installed
  • Download or clone this repository into $GOPATH/src/github.com/CrunchyData/pg_featureserv
  • To build the executable, run the following commands:
cd $GOPATH/src/github.com/CrunchyData/pg_featureserv/
go build
  • This creates a pg_featureserv executable in the application directory
  • (Optional) Run the unit tests using go test ./...

Build a Docker image

  • Build the pg_featureserv executable with the command:
CGO_ENABLED=0 go build

to avoid the runtime error /lib64/libc.so.6: version 'GLIBC_2.XX' not found (required by ./pg_featureserv).

  • In the $GOPATH/src/github.com/CrunchyData/pg_featureserv/ directory, build the Docker image with:
docker build -f container/Dockerfile --build-arg VERSION=<VERSION> -t crunchydata/pg_featureserv:<VERSION> ./

Replace version <VERSION> with the pg_featureserv version you are building against.

Configure the service

The configuration file is automatically read from the following locations, if it exists:

  • In the system configuration directory, at /etc/pg_featureserv.toml
  • Relative to the directory from which the program is run, ./config/pg_featureserv.toml
  • In a root volume at /config/pg_featureserv.toml

To specify a configuration file directly use the --config commandline parameter. In this case configuration files in other locations are ignored.

Configuration Using Environment Variables

To set the database connection the environment variable DATABASE_URL can be used with a Postgres connection string:

export DATABASE_URL="host=localhost user=postgres"

Other parameters in the configuration file can be over-ridden in the environment. Prepend the upper-cased parameter name with PGFS_section_ to set the value. For example, to change the HTTP port and service title:

export PGFS_SERVER_HTTPPORT=8889
export PGFS_METADATA_TITLE="My PGFS"

SSL

For SSL support, a server private key and an authority certificate are needed. For testing purposes you can generate a self-signed key/cert pair using openssl:

openssl req  -nodes -new -x509  -keyout server.key -out server.crt

These are set in the configuration file:

TlsServerCertificateFile = "/path/server.crt"
TlsServerPrivateKeyFile = "/path/server.key"

Run the service

  • Change to the application directory:
    • cd $GOPATH/src/github.com/CrunchyData/pg_featureserv
  • Start the server:
    • ./pg_featureserv
  • Open the service home page in a browser:
    • http:/localhost:9000/home.html

Command-line options

  • -? - show command usage
  • --config file.toml - specify configuration file to use
  • --debug - set logging level to TRACE (can also be set in config file)
  • --devel - run in development mode (e.g. HTML templates reloaded every query)
  • --test - run in test mode, with an internal catalog of tables and data
  • --version - display the version number

Troubleshooting

To get detailed information about service operation run with the --debug commandline parameter.

./pg_featureserv --debug

Debugging can also be enabled via the configuration file (Server.Debug=true), or in the environment:

export PGFS_SERVER_DEBUG=true

Requests Overview

Features are identified by a collection name and feature id pair.

The default response is in JSON/GeoJSON format. Append .html to the request path to see the UI page for the resource. In a web browser, to request a JSON response append .json to the path (which overrides the browser Accept header).

The example requests assume that the service is running locally and configured to listen on port 9000.

See API Summary for a summary of the web service API.