Skip to content

Files

This branch is 7 commits behind geopython/pygeoapi:master.

docker

pygeoapi Docker How To

Overview

pygeoapi's official Docker image is available on Docker Hub. geopython/pygeoapi:latest is the latest image based on the master branch; there also exist images for official releases/versions.

Build workflow

The latest version is automatically built whenever code in the master branch of this GitHub repository changes (autobuild).

This also cascades to updating the pygeoapi demo master service.

So the build chain is as per below:

 (git push to master) --> (Docker Hub image autobuild) --> (demo.pygeoapi.io server redeploy)

Setup

The official Docker image ships with a default configuration default.config.yml with the project's test data and OGC API dataset collections.

You can override this default config via a Docker volume mapping or by extending the Docker image and copying in your config. See an example from the pygeoapi demo server for the latter method.

Installing on a fresh Ubuntu installation

# install Docker

sudo apt-get install -y apt-transport-https
sudo apt-get install -y ca-certificates
sudo apt-get install -y curl
sudo apt-get install -y gnupg-agent
sudo apt-get install -y software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add –
sudo apt-key fingerprint 0EBFCD88
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable docker

# pull official pygeoapi image from Docker Hub

docker pull geopython/pygeoapi

# Create your own configuration in $HOME/my.config.yml
# Example can be found in https://github.com/geopython/pygeoapi-examples/blob/main/docker/simple/my.config.yml
vi $HOME/my.config.yml

# run and create container

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

At this point, go to http://localhost:5000 and the service should be up and running.

Running - basics

By default, this image will start a pygeoapi Docker container using gunicorn running on port 80 internally.

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

Running - overriding the default config

Normally you would override the default.config.yml with your own configuration.

This can be achieved using 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

You can also achieve the same using Docker Compose:

version: "3"

services:
  pygeoapi:
    image: geopython/pygeoapi:latest
    volumes:
      - ./my.config.yml:/pygeoapi/local.config.yml

Or, you can create a Dockerfile extending the base image and COPY in your config:

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

An example using the demo server setup can be found at https://github.com/geopython/demo.pygeoapi.io/tree/master/services/pygeoapi_master.

Running - running on a sub-path

By default the pygeoapi Docker image will run from the root path of the web server (/).

If you need to run from a sub-path and have all internal URLs correct, you need to set 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
# browse to http://localhost:5000/mypygeoapi

You can also achieve the same using Docker Compose:

version: "3"

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

See the pygeoapi demo service for a full example.

More examples

The pygeoapi examples repository contains a number of sample deployment configurations. See the docker directory for Docker and Docker Compose specific examples.