-
-
Notifications
You must be signed in to change notification settings - Fork 6
/
README.Rmd
257 lines (186 loc) · 12.8 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
---
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://github.com/geocompx/docker/blob/master/)
This repo documents Docker images for geographic research and reproducing code in the books *Geocomputation with R* and *Geocomputation with Python*.
The Dockerfiles build on work done for the [Rocker Project](https://www.rocker-project.org/).
As documented on the Rocker Project website, Docker can save time and increase reproducibility by providing an environment with up-to-date and stable software.
To get started, after you [install Docker](https://docs.docker.com/get-docker/), try running one of the following commands:
```{r, engine='bash', eval=FALSE}
# The latest version of rocker/geospatial + geocompr dependencies
docker run -e PASSWORD=pw --rm -p 8786:8787 ghcr.io/geocompx/docker
# With up-to-date OSGeo packages and qgisprocess:
docker run -e PASSWORD=pw --rm -p 8786:8787 ghcr.io/geocompx/docker:osgeo
```
If you are asked for a username and password, then you should use `rstudio` as your username and the password you set with the above code (e.g., `pw`).
Then open a browser at http://localhost:8786/, and you should see something like this:
If so congratulations 🎉 you can proceed to open the `geocompr.Rproj` project or other files in the `geocompr` folder, which contains a complete copy of the source code and example data needed to build the html version of the book.
To run a container without RStudio, try the following.
```
docker run -e PASSWORD=pw --rm -ti ghcr.io/geocompx/docker /bin/bash
```
Use this resource to play with the examples, develop new answers to the questions at the end of each page, or even to generate reproducible examples to illustrate [issues](https://github.com/geocompx/geocompr/issues) with the books contents.
If not, see documentation on using Docker at websites such as [docker.com](https://docs.docker.com/get-started/) and https://www.rocker-project.org/.
## Sharing folders with Docker
To use these Docker images for your own work you will need to share files with Docker.
That means sharing 'volumes'.
You can do this using the `-v` argument as shown below, which shares your current working directory with the Docker container.
If you run these commands in a terminal that has access to Docker, like `bash` or Windows `PowerShell` you should get a local copy of *Geocomputation with R* on your computer that you can use for testing and development purposes, e.g. to test changes before submitting a Pull Request to improve the book:
```bash
# download repo with Windows Powershell or a Unix terminal
git clone https://github.com/geocompx/geocompr.git
# or download manually from https://github.com/geocompx/geocompr/archive/main.zip
cd geocompr # navigate into the repo
# on linux and mac with password:
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e USERID=$UID -e PASSWORD=pw ghcr.io/geocompx/docker:minimal
# on linux and mac without password:
docker run -d -p 8786:8787 -e DISABLE_AUTH=TRUE -v $(pwd):/home/rstudio/geocompr ghcr.io/geocompx/docker:minimal
```
If you see something like this after following the steps above, congratulations: it worked!
See [github.com/rocker-org](https://github.com/rocker-org/rocker/wiki/Using-the-RStudio-image#running-rstudio-server) for more info.
You can also pull and run the same images from ghcr.io, e.g. as follow:
```bash
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e PASSWORD=pw ghcr.io/ghcr.io/geocompx/docker:minimal
```
From this point to *build* the book you can open projects in the `geocompr` directory from the project box in the top-right hand corner, and knit `index.Rmd` with the little `knit` button above the the RStudio script panel (`Ctl+Shift+B` should do the same job).
There are various versions of the `geocompr` Docker image available.
The default is the `latest` tag, representing the `Dockerfile` in the root of this repo, but you can get other images, as outlined below.
## Versions
Building on the [rocker-org](https://github.com/rocker-org/rocker-versioned/blob/master/README.md) project, we provide various versions for testing and development, including builds that use more up-to-date versions of OSGeo packages such as GDAL provided by the [UbuntuGIS software repository](https://wiki.ubuntu.com/UbuntuGIS), as shown below:
image | description | size
---------------- | ----------------------------------------- | ------
[docker:latest](https://github.com/geocompx/docker/pkgs/container/docker/) | docker pull ghcr.io/ghcr.io/geocompx/docker:latest image + book files | 
[docker:minimal](https://github.com/geocompx/docker/blob/master/minimal) | docker pull ghcr.io/ghcr.io/geocompx/docker:minimal rocker/geospatial plus geocompkg Imports | 
[docker:suggests](https://github.com/geocompx/docker/blob/master/suggests) | docker pull ghcr.io/ghcr.io/geocompx/docker:suggests includes all packages from geocompkgs (Suggests) | 
[docker:binder](https://github.com/geocompx/docker/blob/master/binder) | docker pull ghcr.io/ghcr.io/geocompx/docker:binder runs with Binder | 
[docker:osgeo](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:osgeo running on rocker/geospatial:osgeo | 
[docker:buildbook](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:buildbook runs the book code | 
[docker:qgis](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:qgis with QGIS | 
[docker:rocker-rpy](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:rocker-rpy with python | 
[docker:rocker-rpyjl](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:rocker-rpyjl with R, Python, and Julia | 
[docker:python](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:python Python image + geo pkgs | 
[docker:rust](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:rust with Rust | 
[docker:pixi-r](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:pixi-r | 
[docker:pixi-py](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:pixi-py | 
[docker:pixi-rpy](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:pixi-rpy | 
[docker:mamba-py](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:mamba-py | 
[docker:mamba-pyr](https://github.com/geocompx/docker/blob/master/) | docker pull ghcr.io/ghcr.io/geocompx/docker:mamba-pyr | 
The base image is `rocker/geospatial` from [github.com/rocker-org/rocker-versioned2](https://github.com/rocker-org/rocker-versioned2).
Add :tagname after ghcr.io/geocompx/docker to get the image you want.
<!-- To run the `buildbook` version (represented by the extension `-b` for most tags), for example, run the following command (with port and password set to a port of your preference): -->
```{r, engine='bash', eval=FALSE}
docker run -e PASSWORD=pw --rm -p 8786:8787 ghcr.io/geocompx/docker:buildbook
```
### Note on pixi based images in devcontainers
For [reasons we don't understand on the pixi side](https://github.com/prefix-dev/pixi/discussions/2088), you must set the locale with something like
```
"postCreateCommand": "apt update && apt install -y --no-install-recommends locales; echo \"en_US.UTF-8 UTF-8\" >> /etc/locale.gen; locale-gen",
```
If you use these in a [devcontainer](https://github.com/geocompx/geocompr/blob/77dd6207c3b0e1a51d62202c62d5d045c2961038/.devcontainer.json#L1-L9).
## Examples
### osgeo
To test your code or package against recent versions of OSGeo libraries (GDAL, GEOS, PROJ), you can run the following command from inside root directory of the folder containing the code:
```bash
# on linux and mac with password:
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data \
-e USERID=$UID -e PASSWORD=pw ghcr.io/geocompx/docker:osgeo
```
### Python
The Python tag contains Python geospatial packages:
```bash
docker run -e PASSWORD=pw --rm -ti ghcr.io/geocompx/docker:python /bin/bash
python3
import pandas as pd
import geopandas as gpd
import movingpandas as mpd
```
You can run an interactive session via Reticulate in RStudio as follows:
```bash
docker run -e PASSWORD=pw --rm -p 8786:8787 ghcr.io/geocompx/docker:python
```
And then in the resulting RStudio session you can enter something along the lines of:
```r
library(sf)
f = file.path(system.file("shape/nc.shp", package="sf"))
nc_sf = read_sf(f)
library(reticulate)
system("pip3 install descartes")
gp = import("geopandas")
nc_gp = gp$read_file(f)
class(nc_gp)
plot(nc_gp$AREA, nc_gp$PERIMETER)
gp = import("geopandas", convert = FALSE)
nc_gp = gp$read_file(f)
nc_gp
plt = import("matplotlib.pyplot", convert = FALSE)
nc_gp$plot()
plt$savefig("test.png")
```
To plot from Python packages (work in [progress](https://github.com/geocompr/docker/issues/12)).
### QGIS
To run QGIS from the command line, you can run:
```bash
docker pull ghcr.io/geocompx/docker:qgis
docker run --rm -ti ghcr.io/geocompx/docker:qgis /bin/bash
qgis --version
# QGIS 3.20.3-Odense 'Odense' (495fbaecaf)
```
You can also run QGIS algorithms via the `qgisprocess` package as follows:
```
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e PASSWORD=pw ghcr.io/geocompx/docker:qgis
```
Then open a browser and the local url such as http://192.168.0.99:8786/ or http://localhost:8786, enter RStudio server, and you should be able to access QGIS as follows in the R console:
```{r, eval=FALSE}
system("qgis --version")
## QGIS 3.16.1-Hannover 'Hannover' (b381a90dca)
remotes::install_github("paleolimbot/qgisprocess") # install the latest version of the package
qgis_algs = qgisprocess::qgis_algorithms()
nrow(qgis_algs)
## [1] 303
table(qgis_algs$provider)
## 3d gdal native qgis
## 1 55 196 51
```
### QGIS extensions
You can access algorithms from other GIS programs through QGIS but they need to be installed.
These can be accessed from the `ghcr.io/geocompx/docker:qgis` image as follows:
```
docker run -d -p 8786:8787 -v $(pwd):/home/rstudio/data -e PASSWORD=pw ghcr.io/geocompx/docker:qgis
```
Again, open the browser, e.g. at http://localhost:8786, and find the new algorithms as follows:
```{r, eval=FALSE}
system("qgis --version")
## QGIS 3.16.1-Hannover 'Hannover' (b381a90dca)
remotes::install_github("paleolimbot/qgisprocess") # install the latest version of the package
## Skipping install of 'qgisprocess' from a github remote, the SHA1 (6e378511) has not changed since last install.
qgis_algs = qgisprocess::qgis_algorithms()
nrow(qgis_algs)
## [1] 970
table(qgis_algs$provider)
## 3d gdal grass7 native qgis saga
## 1 55 301 196 51 366
```
Congratulations, you now have nearly 1000 QGIS algorithms at your disposal from the R command line 🎉
## Building the images locally
You can build the images locally, e.g. as follows:
```bash
docker build qgis -t test
docker run -p 8888:8888 test
docker build conda -t geocompy
docker run -it geocompy /bin/bash
docker build -t
```
You should then be able to run commands in the newly created images, e.g. with:
```bash
docker run -it /bin/bash
```