Docker

pygeoapi provides an official Docker image which is made available on both the geopython Docker Hub and our GitHub Container Registry. Additional Docker examples can be found in the pygeoapi GitHub repository, each with sample configurations, test data, deployment scenarios and provider backends.

The pygeoapi demo server runs various services from Docker images which also serve as useful examples.

Note

Both Docker and Docker Compose are required on your system to run pygeoapi images.

The basics

The official pygeoapi Docker image will start a pygeoapi Docker container using Gunicorn on internal port 80.

Either IMAGE can be called with the docker command, geopython/pygeoapi from DockerHub or ghcr.io/geopython/pygeoapi from the GitHub Container Registry. Examples below use geopython/pygeoapi.

To run with the default built-in configuration and data:

docker run -p 5000:80 -it geopython/pygeoapi run
# or simply
docker run -p 5000:80 -it geopython/pygeoapi

…then browse to http://localhost:5000

You can also run all unit tests to verify:

docker run -it geopython/pygeoapi test

Overriding the default configuration

Normally you would override the default.config.yml with your own pygeoapi configuration. This can be done via Docker Volume Mapping.

For example, if your config is in my.config.yml:

docker run -p 5000:80 -v $(pwd)/my.config.yml:/pygeoapi/local.config.yml -it geopython/pygeoapi

For a cleaner approach, You can use docker-compose as per below:

version: "3"
services:
  pygeoapi:
    image: geopython/pygeoapi:latest
    volumes:
      - ./my.config.yml:/pygeoapi/local.config.yml
    ports:
      - "5000:80"

Or you can create a Dockerfile extending the base image and copy in your configuration:

FROM geopython/pygeoapi:latest
COPY ./my.config.yml /pygeoapi/local.config.yml

A corresponding example can be found in https://github.com/geopython/demo.pygeoapi.io/tree/master/services/pygeoapi_master

Deploying on a sub-path

By default the pygeoapi Docker image will run from the root path (/). If you need to run from a sub-path and have all internal URLs properly configured, you can set the SCRIPT_NAME environment variable.

For example to run with my.config.yml on http://localhost:5000/mypygeoapi:

docker run -p 5000:80 -e SCRIPT_NAME='/mypygeoapi' -v $(pwd)/my.config.yml:/pygeoapi/local.config.yml -it geopython/pygeoapi

…then browse to http://localhost:5000/mypygeoapi

Below is a corresponding docker-compose approach:

version: "3"
services:
  pygeoapi:
    image: geopython/pygeoapi:latest
    volumes:
      - ./my.config.yml:/pygeoapi/local.config.yml
    ports:
      - "5000:80"
    environment:
     - SCRIPT_NAME=/pygeoapi

A corresponding example can be found in https://github.com/geopython/demo.pygeoapi.io/tree/master/services/pygeoapi_master

Summary

Docker is an easy and reproducible approach to deploying systems.

Note

Additional approaches are welcome and encouraged; see Contributing for more information on how to contribute to and improve the documentation