Skip to content

update Docker container offerings #1753

Open

Description

@tomkralidis

Currently, pygeoapi produces Docker images via GitHub Actions to the following container registries:

Currently, the latest image is ~1.5GB containing numerous optional dependencies. It would be valuable to offer various images based on different deployment profiles/environments.

  • determine images to produce (e.g. slim, default, full)
  • add/update Dockerfile setups accordingly
  • update GitHub Action for container publication
  • update documentation

cc @justb4 @francbartoli @webb-ben @ricardogsilva

Activity

  1. added this to the 0.19.0 milestone on Jul 24, 2024
  2. github-actions commented on Oct 27, 2024

    @github-actions

    This Issue has been inactive for 90 days. As per RFC4, in order to manage maintenance burden, it will be automatically closed in 7 days.

  3. kalxas commented on Oct 27, 2024

    @kalxas
    Member

    I have been experimenting with a slim version of our Docker image. I agree it would be good to have different images for different use cases.

  4. modified the milestones: 0.19.0, 0.20.0 on Dec 31, 2024
  5. mattdear commented on Mar 7, 2025

    @mattdear

    I have started using Pygeoapi recently and I am interested in trying to reduce the image size and resource requirements for cheaper cloud deployments and improved security.

    I was thinking about trying to build the pygeoapi image with the Ubuntu/python base. https://hub.docker.com/r/ubuntu/python

    @kalxas can I ask what base images you have tried? And how successful you have been?

  6. modified the milestones: 0.20.0, 0.21.0 on Mar 27, 2025
  7. mikebelanger commented on Apr 15, 2025

    @mikebelanger

    I'd be interested in what you've found too @kalxas.

  8. 27 remaining items

  9. webb-ben commented on Jul 9, 2026

    @webb-ben
    Member

    Were there any conclusions from the pygeoapi Docker survey? https://lists.osgeo.org/pipermail/pygeoapi/2026-February/000481.html

  10. tomkralidis commented on Jul 9, 2026

    @tomkralidis
    MemberAuthor

    The proposal is that Python packages are not derived from Ubuntu system dependencies. We'll have the work in a PR once the next release is complete.

  11. modified the milestones: 0.24.0, 0.25.0 on Jul 13, 2026
  12. jorgejesus commented on Jul 22, 2026

    @jorgejesus
    Member

    First comment: Issue #2392 is a blocker of the new docker implementations
    To test current docker proposals:

    Everything is self-contained under docker-proposals/; the current Dockerfile is untouched, so nothing in the repo changes until we agree on a direction.

    All five build and serve. This also resolves #2221 (pure pip no gunicorn/gevent mismatch) and #2180 (geopandas in standard/full).

    To test:

    git clone -b docker-variants https://github.com/terraops-org/pygeoapi.git
    cd pygeoapi
    docker build -f docker-proposals/Dockerfile.slim -t pygeoapi:slim .
    docker run -p 5000:80 pygeoapi:slim
     # tge same pattern for Dockerfile.alpine / .distroless / .standard / .full

    These are my resilts

    Variant base Python size (uncompressed / compressed)
    slim ubuntu:26.04 LTS 3.14 429 MB / ~144 MB
    distroless (experimental) distroless/python3-debian13 3.13 272 MB / ~89 MB
    standard osgeo/gdal:ubuntu-small-3.12.4 3.12 1.07 GB
    full osgeo/gdal:ubuntu-small-3.12.4 3.12 1.06 GB
    alpine (experiment) python:alpine 3.12 312 MB / ~97 MB
  13. justb4 commented on Jul 22, 2026

    @justb4
    Member

    My comments. I support the idea of multiple Docker images. I would follow another approach. At least with more unification and common conventions. And maybe start with two variants and build, like slim and full and work from there on possibly intermediate variants. My feeling is that the above approach has drawbacks:

    • variation in base images and install commands
    • use of a mix of Debian and PyPi packages and custom compiles
    • a GDAL Base image is handy, but may give other complexities (versions etc) and the size gain may be small
    • these days the Ubuntu Docker Image already very small, 75-80 MB uncompressed
    • all these different environments need their own security patching

    IMHO the above approach will make maintenance quite hard. The mix of Debian, Ubuntu-GIS and PyPi packages and custom compiles has felt always awkward to me, at the time I did not know better..., unless we could rely completely on one repo like Debian.

    Our (pygeoapi's) main problem is that we need Python and non-Python (like GDAL) dependencies. Most Python environment managers like venv, pyenv and even uv cannot deal with non-Python dependencies, or take the "wheel-route".
    I shared this document several times, but for me was en eye-opener:
    https://www.nijho.lt/post/python-environments/ and subsequently:
    https://codecookcash.substack.com/p/simplifying-dependency-management

    How I would approach this? BTW Appreciating the work @jorgejesus has already done!

    I just spent quite some time on GeoHealthCheck cleaning. The main approach that helped me was to first standardize package management:

    • from a bunch of requirements.txt files standardized to pyproject.toml also part of the Python standard (IMHO)
    • introduced Pixi (thanks @francbartoli !) as Python Environment manager
    • all dependencies, inclding binary, multiple environments within a single .pixi directory no more system-wide "Proj" libs
    • slimmed the Dockerfile with a Pixi multi-stage build, copy-ing even all binary dependencies
    • Pixi is not even needed at runtime in Dockerfile

    The main asset here is that Pixi is built on top of Conda and uv and uses both the PyPi and Conda Channels. Blazing fast as well.
    (Though I never tested with GDAL, but many Data Science folks use Conda and Mamba family.)

    The whole bunch is now much better maintainable, but also for local testing, even linestepping within Pycharm and once even connecting to Docker Container. Version management in one place, warnings when misaligning versions.

    Long story. But the whole approach has just two main files and a README, see these GeoHealthCheck files:

    I would first start with Pixi (or maybe one from the Conda family), streamline the whole dep management, redesign the current Dockerfile and then split into the Slim, Full etc.

    This is quite some effort, I probably spent days, also as the whole Pixi-Conda thing was new for me (never too old to learn!). But am very happy I did!

  14. tomkralidis commented on Jul 22, 2026

    @tomkralidis
    MemberAuthor

    I think the general principle is that Python packages are not derived from Ubuntu system dependencies. The next question centres around.

    @jorgejesus any details on using osgeo/gdal as the base image for standard/full images (vs. UbuntuGIS PPA'ing them)? So this would mean similar to the slim option, adding GDAL/etc. via UbuntuGIS.

  15. justb4 commented on Jul 22, 2026

    @justb4
    Member

    Just tested Pixi with GDAL (as GDAL is no dep in GHC) but added as test temporary. By default Pixi will use system GDAL (when added to dependencies) which has to match version, but it is also possible to get GDAL as a Conda package within the Pixi .pixi/ env-bundle. This added around 150MB to the .pixi libs. Within Docker about 250MB uncompressed. A full GDAL I expect. The latter number is more reliable, as maybe are system-deps (GEOS?) may have been used.

    To use GDAL from Conda channel: pixi add GDAL, then it is added at the right places in pyproject.toml.

    Edit: using GDAL Base image could still be a good option! I am staying away a bit from Alpine, unless using self-contained Image like PostGIS.

  16. francbartoli commented on Jul 23, 2026

    @francbartoli
    Contributor

    My comments. I support the idea of multiple Docker images. I would follow another approach. At least with more unification and common conventions. And maybe start with two variants and build, like slim and full and work from there on possibly intermediate variants. My feeling is that the above approach has drawbacks:

    • variation in base images and install commands
    • use of a mix of Debian and PyPi packages and custom compiles
    • a GDAL Base image is handy, but may give other complexities (versions etc) and the size gain may be small
    • these days the Ubuntu Docker Image already very small, 75-80 MB uncompressed
    • all these different environments need their own security patching

    IMHO the above approach will make maintenance quite hard. The mix of Debian, Ubuntu-GIS and PyPi packages and custom compiles has felt always awkward to me, at the time I did not know better..., unless we could rely completely on one repo like Debian.

    Our (pygeoapi's) main problem is that we need Python and non-Python (like GDAL) dependencies. Most Python environment managers like venv, pyenv and even uv cannot deal with non-Python dependencies, or take the "wheel-route". I shared this document several times, but for me was en eye-opener: https://www.nijho.lt/post/python-environments/ and subsequently: https://codecookcash.substack.com/p/simplifying-dependency-management

    How I would approach this? BTW Appreciating the work @jorgejesus has already done!

    I just spent quite some time on GeoHealthCheck cleaning. The main approach that helped me was to first standardize package management:

    • from a bunch of requirements.txt files standardized to pyproject.toml also part of the Python standard (IMHO)
    • introduced Pixi (thanks @francbartoli !) as Python Environment manager
    • all dependencies, inclding binary, multiple environments within a single .pixi directory no more system-wide "Proj" libs
    • slimmed the Dockerfile with a Pixi multi-stage build, copy-ing even all binary dependencies
    • Pixi is not even needed at runtime in Dockerfile

    The main asset here is that Pixi is built on top of Conda and uv and uses both the PyPi and Conda Channels. Blazing fast as well. (Though I never tested with GDAL, but many Data Science folks use Conda and Mamba family.)

    The whole bunch is now much better maintainable, but also for local testing, even linestepping within Pycharm and once even connecting to Docker Container. Version management in one place, warnings when misaligning versions.

    Long story. But the whole approach has just two main files and a README, see these GeoHealthCheck files:

    I would first start with Pixi (or maybe one from the Conda family), streamline the whole dep management, redesign the current Dockerfile and then split into the Slim, Full etc.

    This is quite some effort, I probably spent days, also as the whole Pixi-Conda thing was new for me (never too old to learn!). But am very happy I did!

    I'm totally supportive of this direction, I wrote almost all the migration to pixi of GHC with the experience done during OGC sprint in Nov 2025. I paste here an example of a minimal pixi.toml for GDAL binaries coming from different channels, the dev one is the conda channel from GDAL nightly builds. Hope it is useful to figure out the grade of freedom that pixi would open for developers and maintainers.

    # pixi.toml
    [workspace]
    authors = ["Francesco Bartoli <xbartolone@gmail.com>"]
    # conda-forge only at workspace level: it is the default channel
    # for every environment that does not override it
    channels = ["conda-forge"]
    name = "pygeoapi"
    # Multi-platform guarantee: pixi solves and locks every environment
    # for all the platforms listed here, so pixi.lock is reproducible on
    # Apple Silicon, Intel macOS, Linux (x86_64/ARM) and Windows alike
    platforms = ["osx-arm64", "osx-64", "linux-64", "linux-aarch64", "win-64"]
    version = "0.1.0"
    
    # ---------------------------------------------------------------
    # Dependencies and tasks shared by all environments
    # ---------------------------------------------------------------
    [dependencies]
    python = ">=3.14"
    
    [tasks]
    gdal-version = "python -c \"from osgeo import gdal; print('GDAL version:', gdal.__version__)\""
    
    # ---------------------------------------------------------------
    # Feature "main": stable runtime, conda-forge only, GDAL 3.x
    # ---------------------------------------------------------------
    [feature.main.dependencies]
    gdal = "<4"
    libgdal-core = "<4"
    
    # ---------------------------------------------------------------
    # Feature "dev": development of embryonic features against GDAL
    # builds coming from the gdal-master channel (nightly/master)
    # ---------------------------------------------------------------
    [feature.dev]
    # priority = 1 > 0 (default for workspace channels), so in this
    # environment gdal-master wins over conda-forge for the packages
    # it publishes
    channels = [{ channel = "gdal-master", priority = 1 }]
    
    [feature.dev.dependencies]
    # No upper bound: we want the development builds (e.g. 4.0.0devYYYYMMDD)
    gdal = "*"
    libgdal-core = "*"
    ipython = ">=9.6.0,<10"
    
    [feature.dev.tasks]
    shell = "ipython"
    
    # ---------------------------------------------------------------
    # Environments
    # ---------------------------------------------------------------
    [environments]
    default = { features = ["main"], solve-group = "main" }
    dev = { features = ["dev"] } 
  17. github-actions commented on Oct 25, 2026

    @github-actions

    This Issue has been inactive for 90 days. As per RFC4, in order to manage maintenance burden, it will be automatically closed in 7 days.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions