KoalaGeo
8cd1e737f2
* Create ghcr.yml Create and publish a Docker image to GitHub Container Registry * Update installation.rst Add reference to GitHub Container registry * Update running-with-docker.rst Add ghcr references * Make ghcr conditional on main.yml Updated main.yml run conditions & add on-success condition to ghcr.yml * Miss aligned * change workflow name GHCR * Update build to Build Names didn't match GHCR condition * Remove cog symbol from Build name * Add paths-ignore **.md * Added build & push to DockerHub * Add authorship & update header * Tidy yml, add on-success condition * Add on failure condition * Remove GHC Tests and Conditional Push * DockerHub Test - koalageo/pygeoapi * DockerHub - Revert to geopython/pygeoapi * Use SECRET for DockerHub repo * Combined Build & Push * Update tag function * Fix tags for latest * Lastest tag only on `master` * Use tag on push tag event * Add latest tag on default branch * Add unit tests step * Add separate build & test steps * Typo in docs * Move flake8 to before tests - catch errors early * Add further tags Co-authored-by: Benjamin Webb <40066515+webb-ben@users.noreply.github.com> Co-authored-by: Benjamin Webb <40066515+webb-ben@users.noreply.github.com>
123 lines
3.9 KiB
ReStructuredText
123 lines
3.9 KiB
ReStructuredText
.. _running-with-docker:
|
|
|
|
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:
|
|
|
|
.. code-block:: 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:
|
|
|
|
.. code-block:: bash
|
|
|
|
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``:
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code-block:: yaml
|
|
|
|
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:
|
|
|
|
.. code-block:: dockerfile
|
|
|
|
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``:
|
|
|
|
.. code-block:: bash
|
|
|
|
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:
|
|
|
|
.. code-block:: yaml
|
|
|
|
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 :ref:`contributing` for more information on
|
|
how to contribute to and improve the documentation
|
|
|
|
|
|
.. _`Docker`: https://www.docker.com
|
|
.. _`geopython Docker Hub`: https://hub.docker.com/r/geopython/pygeoapi
|
|
.. _`GitHub Container Registry`: https://github.com/geopython/pygeoapi/pkgs/container/pygeoapi
|
|
.. _`pygeoapi GitHub repository`: https://github.com/geopython/pygeoapi
|
|
.. _`pygeoapi demo server`: https://demo.pygeoapi.io
|
|
.. _`useful examples`: https://github.com/geopython/demo.pygeoapi.io/tree/master/services
|
|
.. _`Docker Compose`: https://docs.docker.com/compose/
|