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/geophython/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