Tom Kralidis
145 lines
4.7 KiB
Markdown
145 lines
4.7 KiB
Markdown
# pygeoapi Docker How To
|
||
|
||
## Overview
|
||
|
||
pygeoapi's official Docker image is available on [Docker Hub](https://hub.docker.com/r/geopython/pygeoapi). `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](https://demo.pygeoapi.io/master).
|
||
|
||
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](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](https://github.com/geopython/demo.pygeoapi.io/tree/master/services/pygeoapi) for the latter method.
|
||
|
||
## Installing on a fresh Ubuntu installation
|
||
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
docker run -it geopython/pygeoapi test
|
||
```
|
||
|
||
## Running - overriding the default config
|
||
|
||
Normally you would override the [default.config.yml](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`:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```yaml
|
||
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:
|
||
|
||
```dockerfile
|
||
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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```yaml
|
||
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](https://github.com/geopython/demo.pygeoapi.io/tree/master/services/pygeoapi) for a full example.
|
||
|
||
## More examples
|
||
|
||
The [pygeoapi examples](https://github.com/geopython/pygeoapi-examples) repository contains a number of sample deployment configurations. See
|
||
the [docker](https://github.com/geopython/pygeoapi-examples/tree/main/docker) directory for Docker and Docker Compose specific examples.
|