README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# Geocomputation with Docker

[![](https://img.shields.io/docker/pulls/geocompx/docker?style=plastic)](https://github.com/geocompx/docker/blob/master/)

This repo provides Docker images for geographic research and reproducing code from the books *Geocomputation with R* and *Geocomputation with Python*, building on the [Rocker Project](https://www.rocker-project.org/).

```{r, engine='bash', eval=FALSE}
# Latest rocker/geospatial + geocompr dependencies
docker run -e PASSWORD=pw --rm -p 8786:8787 ghcr.io/geocompx/latest
# With up-to-date OSGeo packages and qgisprocess:
docker run -e PASSWORD=pw --rm -p 8786:8787 ghcr.io/geocompx/osgeo
```

Log in at http://localhost:8786/ with username `rstudio` and the password from the command (e.g. `pw`).

```{r, engine='bash', eval=FALSE}
# Shell-only, no RStudio:
docker run -e PASSWORD=pw --rm -ti ghcr.io/geocompx/latest /bin/bash
# Bind-mount your working directory:
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e PASSWORD=pw ghcr.io/geocompx/minimal
# Pin a specific version (date tag):
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e PASSWORD=pw ghcr.io/geocompx/minimal:date_2024-10-14
```

## Devcontainers and VS Code support

The R-enabled images (`latest`, `minimal`, `osgeo`, `pythonr`) support VS Code Devcontainers. Open the repo in VS Code and it will detect the `.devcontainer/devcontainer.json` configuration automatically.

## Versions

The base image is `rocker/geospatial` from [rocker-versioned2](https://github.com/rocker-org/rocker-versioned2). We provide variants with different package sets and library versions:

```{r, include=FALSE}
imgs = readr::read_csv("image-info.csv")
imgs <- imgs[order(imgs$size), ]
imgs$Image = paste0("[", imgs$image_name, "](https://ghcr.io/geocompx/", imgs$image_name, ":latest)")
imgs$Command = paste0("[", imgs$command, "](https://github.com/geocompx/docker/blob/master/", 
  ifelse(imgs$image_name == "latest", "Dockerfile", paste0(imgs$image_name, "/Dockerfile")), ")")
imgs <- imgs[, c("Image", "Command", "size", "description")]
names(imgs) = c("Image", "Command", "Size", "Description")
```

```{r, echo=FALSE}
knitr::kable(imgs)
```

Add `:tagname` after `ghcr.io/geocompx/<image>` for a specific version (see [packages](https://github.com/geocompx/docker/pkgs/container/minimal)).

### Building leaner custom images

For users who want smaller images or different packages, a reference [`minimal-slim/Dockerfile`](minimal-slim/Dockerfile) shows how to build from `rocker/r-ver` without RStudio or heavy CLI tools, using [`rocker-versioned2` scripts](https://github.com/rocker-org/rocker-versioned2/tree/master/scripts):

```Dockerfile
FROM rocker/r-ver:4.6.0
RUN apt-get update && apt-get install -y --no-install-recommends \
    libgdal-dev libgeos-dev libproj-dev \
    && rm -rf /var/lib/apt/lists/*
RUN install2.r sf terra spData
```

Available rocker-versioned2 scripts:
- [`install_geospatial.sh`](https://github.com/rocker-org/rocker-versioned2/blob/master/scripts/install_geospatial.sh) — GDAL, PROJ, GEOS + sf, terra, raster, stars, sp
- [`install_rstudio.sh`](https://github.com/rocker-org/rocker-versioned2/blob/master/scripts/install_rstudio.sh) — RStudio Server with S6 supervisor
- [`install_python.sh`](https://github.com/rocker-org/rocker-versioned2/blob/master/scripts/install_python.sh) — Python 3 + reticulate
- [`install_tidyverse.sh`](https://github.com/rocker-org/rocker-versioned2/blob/master/scripts/install_tidyverse.sh) — Tidyverse stack
- [`install_quarto.sh`](https://github.com/rocker-org/rocker-versioned2/blob/master/scripts/install_quarto.sh) — Quarto CLI

## Examples

### Python

The `python` image provides Python geospatial packages (pandas, geopandas, movingpandas, osmnx, matplotlib, shapely, seaborn). The `pythonr` image adds R on top.

```bash
docker pull ghcr.io/geocompx/python
docker run -e PASSWORD=pw --rm -ti ghcr.io/geocompx/python /bin/bash
python3 -c "import geopandas; print(geopandas.__version__)"
```

For R + Python interop, run `ghcr.io/geocompx/pythonr` and use `reticulate` from R.

### QGIS

The `qgis` image includes QGIS, GRASS, and SAGA.

```bash
docker run --rm -ti ghcr.io/geocompx/qgis /bin/bash
qgis --version
```

QGIS algorithms are accessible from R via `qgisprocess`:

```{r, eval=FALSE}
pak::pak("paleolimbot/qgisprocess")
qgis_algs = qgisprocess::qgis_algorithms()
nrow(qgis_algs)
table(qgis_algs$provider)
```

With GRASS and SAGA available as providers, you have access to ~970 algorithms.

### osgeo

For testing against recent GDAL/PROJ/GEOS versions:

```bash
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data \
  -e USERID=$UID -e PASSWORD=pw ghcr.io/geocompx/osgeo
```

## Building the images locally

```bash
docker build qgis -t geocompx/qgis
docker build minimal -t geocompx/minimal
```

### Using GitHub PAT with BuildKit secret mounts

Some images (`suggests`, `rust`) install packages from GitHub repositories. Pass a GitHub PAT securely with BuildKit:

```bash
echo "your_github_token" > GITHUB_PAT.txt
DOCKER_BUILDKIT=1 docker build --secret id=GITHUB_PAT,src=GITHUB_PAT.txt -t geocompx/suggests suggests
```