You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -8,54 +8,38 @@ This workshop is designed to be run on your local machine. First, you will need
8
8
9
9
## Data
10
10
11
-
You can download all of the data used in this workshop by clicking
12
-
[this download link](https://ndownloader.figshare.com/articles/2009586/versions/10). The file is 218.2 MB.
11
+
You can download all of the data used in this workshop by clicking [this download link](https://ndownloader.figshare.com/articles/2009586/versions/10). The file is 218.2 MB.
13
12
14
-
Clicking the download link will automatically download all of the files to your default download directory as a single compressed
15
-
(`.zip`) file. To expand this file, double click the folder icon in your file navigator application (for Macs, this is the Finder
16
-
application).
13
+
Clicking the download link will automatically download all of the files to your default download directory as a single compressed (`.zip`) file. To expand this file, double click the folder icon in your file navigator application (for Macs, this is the Finder application).
17
14
18
15
For a full description of the data used in this workshop see the [data page](instructors/data.md).
19
16
20
17
## Option A: Local Installation
21
18
22
19
### Software
23
20
24
-
| Software | Install | Manual | Available for | Description |
|[GDAL](https://www.gdal.org)|[Link](https://gdal.org/download.html)|[Link](https://gdal.org)| Linux, MacOS, Windows | Geospatial model for reading and writing a variety of formats |
27
-
|[GEOS](https://trac.osgeo.org/geos)|[Link](https://trac.osgeo.org/geos)|[Link](https://geos.osgeo.org/doxygen/)| Linux, MacOS, Windows | Geometry models and operations |
28
-
|[PROJ.4](https://proj4.org)|[Link](https://proj4.org/install.html)|[Link](https://proj4.org/index.html)| Linux, MacOS, Windows | Coordinate reference system transformations |
29
-
|[R](https://www.r-project.org)|[Link](https://cloud.r-project.org)|[Link](https://cloud.r-project.org)| Linux, MacOS, Windows | Software environment for statistical and scientific computing |
30
-
|[RStudio](https://www.rstudio.com)|[Link](https://www.rstudio.com/products/rstudio/download/#download)|| Linux, MacOS, Windows | GUI for R |
31
-
|[UDUNITS](https://www.unidata.ucar.edu/software/udunits/)|[Link](https://www.unidata.ucar.edu/downloads/udunits/index.jsp)|[Link](https://www.unidata.ucar.edu/software/udunits/#documentation)| Linux, MacOS, Windows | Unit conversions |
21
+
| Software | Install | Manual | Available for | Description |
|[R](https://www.r-project.org)|[Link](https://cloud.r-project.org)|[Link](https://cloud.r-project.org)| Linux, MacOS | Software environment for statistical and scientific computing |
24
+
|[RStudio](https://www.rstudio.com)|[Link](https://www.rstudio.com/products/rstudio/download/#download)|| Linux, MacOS | GUI for R |
32
25
33
26
We provide quick instructions below for installing the various software needed for this workshop. At points, they assume familiarity with the command line and with installation in general. As there are different operating systems and many different versions of operating systems and environments, these may not work on your computer. If an installation doesn't work for you, please refer to the installation instructions for that software listed in the table above.
34
27
35
-
### GDAL, GEOS, and PROJ.4
36
-
37
-
The installation of the geospatial libraries GDAL, GEOS, and PROJ.4 varies significantly based on operating system. These are all dependencies for `sf`, the `R` package that we will be using for spatial data operations throughout this workshop.
38
-
39
-
:::::::::::::::: spoiler
40
-
28
+
::: spoiler
41
29
## Windows
42
30
43
31
To install the geospatial libraries, install the latest version [RTools](https://cran.r-project.org/bin/windows/Rtools/)
32
+
:::
44
33
45
-
:::::::::::::::::::::::::
46
-
47
-
:::::::::::::::: spoiler
48
-
34
+
::: spoiler
49
35
## macOS - Install with Packages (Beginner)
50
36
51
37
The simplest way to install these geospatial libraries is to install the latest version of [Kyng Chaos's pre-built package](https://www.kyngchaos.com/software/frameworks) for GDAL Complete. Be aware that several other libraries are also installed, including the UnixImageIO, SQLite3, and `NumPy`.
52
38
53
39
After downloading the package in the link above, you will need to double-click the cardbord box icon to complete the installation. Depending on your security settings, you may get an error message about "unidentified developers". You can enable the installation by following [these instructions](https://kb.wisc.edu/page.php?id=25443) for installing programs from unidentified developers.
40
+
:::
54
41
55
-
:::::::::::::::::::::::::
56
-
57
-
:::::::::::::::: spoiler
58
-
42
+
::: spoiler
59
43
## macOS - Install with Homebrew (Advanced)
60
44
61
45
Alternatively, participants who are comfortable with the command line can install the geospatial libraries individually using [homebrew](https://brew.sh):
@@ -65,102 +49,91 @@ $ brew install proj
65
49
$ brew install geos
66
50
$ brew install gdal
67
51
```
52
+
:::
68
53
69
-
:::::::::::::::::::::::::
70
-
71
-
:::::::::::::::: spoiler
72
-
54
+
::: spoiler
73
55
## Linux
74
56
75
57
Steps for installing the geospatial libraries will vary based on which form of Linux you are using. These instructions are adapted from the [`sf` package's `README`](https://github.com/r-spatial/sf).
For **Debian**: The [rocker geospatial](https://github.com/rocker-org/geospatial) Dockerfiles may be helpful. Ubuntu Dockerfiles are found [here](https://github.com/r-spatial/sf/tree/master/inst/docker). These may be helpful to get an idea of the commands needed to install the necessary dependencies.
98
-
99
-
:::::::::::::::::::::::::
80
+
:::
100
81
101
82
### UDUNITS
102
83
103
84
Linux users will have to install UDUNITS separately. Like the geospatial libraries discussed above, this is a dependency for the `R` package `sf`. Due to conflicts, it does not install properly on Linux machines when installed as part of the `sf` installation process. It is therefore necessary to install it using the command line ahead of time.
104
85
105
-
:::::::::::::::: spoiler
106
-
86
+
::: spoiler
107
87
## Linux
108
88
109
89
Steps for installing the geospatial will vary based on which form of Linux you are using. These instructions are adapted from the [`sf` package's `README`](https://github.com/r-spatial/sf).
110
90
111
91
For **Ubuntu**:
112
92
113
-
```bash
93
+
```bash
114
94
$ sudo apt-get install libudunits2-dev
115
95
```
116
96
117
97
For **Fedora**:
118
98
119
-
```bash
99
+
```bash
120
100
$ sudo dnf install udunits2-devel
121
101
```
122
102
123
103
For **Arch**:
124
104
125
-
```bash
105
+
```bash
126
106
$ pacaur/yaourt/whatever -S udunits
127
107
```
128
108
129
109
For **Debian**:
130
110
131
-
```bash
111
+
```bash
132
112
$ sudo apt-get install -y libudunits2-dev
133
113
```
134
-
135
-
:::::::::::::::::::::::::
114
+
:::
136
115
137
116
### R
138
117
139
118
Participants who do not already have `R` installed should download and install it.
140
119
141
-
:::::::::::::::: spoiler
142
-
120
+
::: spoiler
143
121
## Windows
144
122
145
123
To install `R`, Windows users should select "Download R for Windows" from RStudio and CRAN's [cloud download page](https://cloud.r-project.org), which will automatically detect a CRAN mirror for you to use. Select the `base` subdirectory after choosing the Windows download page. A `.exe` executable file containing the necessary components of base R can be downloaded by clicking on "Download R 3.x.x for Windows".
124
+
:::
146
125
147
-
:::::::::::::::::::::::::
148
-
149
-
:::::::::::::::: spoiler
150
-
126
+
::: spoiler
151
127
## macOS
152
128
153
129
To install `R`, macOS users should select "Download R for (Mac) OS X" from RStudio and CRAN's [cloud download page](https://cloud.r-project.org), which will automatically detect a CRAN mirror for you to use. A `.pkg` file containing the necessary components of base R can be downloaded by clicking on the first available link (this will be the most recent), which will read `R-3.x.x.pkg`.
130
+
:::
154
131
155
-
:::::::::::::::::::::::::
156
-
157
-
:::::::::::::::: spoiler
158
-
132
+
::: spoiler
159
133
## Linux
160
134
161
135
To install `R`, Linux users should select "Download R for Linux" from RStudio and CRAN's [cloud download page](https://cloud.r-project.org), which will automatically detect a CRAN mirror for you to use. Instructions for a number of different Linux operating systems are available.
162
-
163
-
:::::::::::::::::::::::::
136
+
:::
164
137
165
138
### RStudio
166
139
@@ -170,29 +143,28 @@ RStudio is a GUI for using `R` that is available for Windows, macOS, and various
170
143
171
144
The following `R` packages are used in the various geospatial lessons.
@@ -221,24 +193,21 @@ This option involves downloading an Docker image that contains an installation o
221
193
222
194
Once up and running - you'll have full access to RStudio right from your browser:
223
195
224
-
{alt='RStudio layout in browser showing similarity to desktop layout'}
196
+
{alt="RStudio layout in browser showing similarity to desktop layout"}
225
197
226
198
Please be aware that the `R` package `rasterVis` is not included in the `rocker/geospatial` Docker image. If your instructor teaches with this package then you will need to install this `R` package yourself. All other `R` packages will already be installed for you.
227
199
228
-
:::::::::::::::: spoiler
229
-
200
+
::: spoiler
230
201
## Downloading and Installing Docker Community Edition
231
202
232
203
To get started with Docker, download the [Docker Community Edition](https://www.docker.com/community-edition) from [Docker's store](https://store.docker.com/search?type=edition&offering=community). Community editions are available for [Windows](https://store.docker.com/editions/community/docker-ce-desktop-windows), [macOS](https://store.docker.com/editions/community/docker-ce-desktop-mac), and Linux operating systems including [Debian](https://store.docker.com/editions/community/docker-ce-server-debian), [Fedora](https://store.docker.com/editions/community/docker-ce-server-fedora), and [Ubuntu](https://store.docker.com/editions/community/docker-ce-server-ubuntu).
233
204
234
205
The download pages for each of these operating systems contain notes about some necessary system requirements and other pre-requisites. Once you download the installer and follow the on-screen prompts.
235
206
236
207
Additional installation notes are available in Docker's documentation for each of these operating systems: [Windows](https://docs.docker.com/docker-for-windows/install/), [macOS](https://docs.docker.com/docker-for-mac/install/), [Debian](https://docs.docker.com/install/linux/docker-ce/debian/), [Fedora](https://docs.docker.com/install/linux/docker-ce/fedora/), and [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/).
208
+
:::
237
209
238
-
:::::::::::::::::::::::::
239
-
240
-
:::::::::::::::: spoiler
241
-
210
+
::: spoiler
242
211
## Using the `rocker/geospatial` Docker Image via the Command Line
243
212
244
213
#### Download and Set-up
@@ -247,23 +216,23 @@ Once Docker is installed and up and running, you will need to open your computer
247
216
248
217
You need to have already installed Docker Community Edition (see instructions above) before proceeding. Once you have Docker downloaded and installed, make sure Docker is running and then enter the following command into the terminal to download the `rocker/geospatial` image:
249
218
250
-
```bash
219
+
```bash
251
220
$ docker pull rocker/geospatial
252
221
```
253
222
254
223
Once the pull command is executed, the image needs to be run to become accessible as a container. In the following example, the image is named `rocker/geospatial` and the container is named `gis`. The [image](https://docs.docker.com/glossary/?term=image) contains the software you've downloaded, and the [container](https://docs.docker.com/glossary/?term=container) is the run-time instance of that image. New Docker users should need only one named container per image.
255
224
256
225
When `docker run` is used, you can specify a folder on your computer to become accessible inside your RStudio Server instance. The following `docker run` command exposes Jane's `GitHub` directory to RStudio Server. Enter the file path where your workshop resources and data are stored:
When she opens her RStudio instance below, she will see a `GitHub` folder in her file tab in the lower righthand corner of the screen. Windows and Linux users will have to adapt the file path above to follow the standards of their operating systems. More details are available on [rocker's Wiki](https://github.com/rocker-org/rocker/wiki/Sharing-files-with-host-machine).
263
232
264
233
The last step before launching your container in a browser is to identify the port that your Docker container is running in:
265
234
266
-
```bash
235
+
```bash
267
236
$ docker port gis
268
237
```
269
238
@@ -273,30 +242,28 @@ An output, for example, of `8787/tcp -> 0.0.0.0:32768` would indicate that you s
273
242
274
243
When you are done with a Docker session, make sure all of your files are saved locally on your computer **before closing your browser and Docker**. Once you have ensured all of your files are available (they should be saved at the file path designated in `docker run` above), you can stop your Docker container in the terminal:
275
244
276
-
```bash
245
+
```bash
277
246
$ docker stop gis
278
247
```
279
248
280
249
#### Re-starting a Container
281
250
282
251
Once a container has been named and created, you cannot create a container with the same name again using `docker run`. Instead, you can restart it:
283
252
284
-
```bash
253
+
```bash
285
254
$ docker start gis
286
255
```
287
256
288
257
If you cannot remember the name of the container you created, you can use the following command to print a list of all named containers:
289
258
290
-
```bash
259
+
```bash
291
260
$ docker ps -a
292
261
```
293
262
294
263
If you are returning to a session after stopping Docker itself, make sure Docker is running again before re-starting your container!
264
+
:::
295
265
296
-
:::::::::::::::::::::::::
297
-
298
-
:::::::::::::::: spoiler
299
-
266
+
::: spoiler
300
267
## Using the `rocker/geospatial` Docker Image via Kitematic
301
268
302
269
#### Download and Install Kitematic
@@ -307,17 +274,17 @@ If you are returning to a session after stopping Docker itself, make sure Docker
307
274
308
275
Once you have installed Kitematic, make sure the Docker application is running and then open Kitematic. You should not need to create a login to use Kitematic. If prompted for login credentials, there is an option to skip that step. Use the search bar in the main window to find `rocker/geospatial` (pictured below) and click `Create` under that Docker repository.
309
276
310
-
277
+
311
278
312
279
After downloading and installing the image, your container should start automatically. Before opening your browser, connect your Docker image to a local folder where you have your workshop resources stored by clicking on the `Settings` tab and then choosing `Volumes`. Click `Change` and then select the directory you would like to connect to.
313
280
314
-
281
+
315
282
316
283
When you open RStudio instance below, you will see the contents of the connected folder inside the `kitematic` directory in the file tab located in the lower righthand corner of the screen.
317
284
318
285
When you are ready, copy the `Access URL` from the `Home` tab:
319
286
320
-
287
+
321
288
322
289
Paste that url into your browser and, if prompted, enter `rstudio` for both the username and the password.
323
290
@@ -326,37 +293,32 @@ Paste that url into your browser and, if prompted, enter `rstudio` for both the
326
293
When you are done with a Docker session, make sure all of your files are saved locally on your computer **before closing your browser and Docker**. Once you have ensured all of your files are available (they should be saved at the file path designated in `docker run` above), you can stop your Docker container by clicking on the `Stop` icon in Kitematic's toolbar.
327
294
328
295
You can restart your container later by clicking the `Restart` button.
296
+
:::
329
297
330
-
:::::::::::::::::::::::::
331
-
332
-
:::::::::::::::: spoiler
333
-
298
+
::: spoiler
334
299
## Managing Docker Containers and Images
335
300
336
301
To obtain a list of all of your current Docker containers:
337
302
338
-
```bash
303
+
```bash
339
304
$ docker ps -a
340
305
```
341
306
342
307
To list all of the currently downloaded Docker images:
343
308
344
-
```bash
309
+
```bash
345
310
$ docker images -a
346
311
```
347
312
348
313
These images can take up system resources, and if you'd like to remove them, you can use the `docker prune` command. To remove any Docker resources not affiliated with a container listed under `docker ps -a`:
349
314
350
-
```bash
315
+
```bash
351
316
$ docker system prune
352
317
```
353
318
354
319
To remove **all** Docker resources, including currently named containers:
0 commit comments