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,160 +8,133 @@ 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):
62
46
63
-
```bash
47
+
```bash
64
48
$ brew tap osgeo/osgeo4mac && brew tap --repair
65
49
$ brew install proj
66
50
$ brew install geos
67
51
$ brew install gdal2
68
52
```
53
+
:::
69
54
70
-
:::::::::::::::::::::::::
71
-
72
-
:::::::::::::::: spoiler
73
-
55
+
::: spoiler
74
56
## Linux
75
57
76
58
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.
99
-
100
-
:::::::::::::::::::::::::
81
+
:::
101
82
102
83
### UDUNITS
103
84
104
85
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.
105
86
106
-
:::::::::::::::: spoiler
107
-
87
+
::: spoiler
108
88
## Linux
109
89
110
90
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).
111
91
112
92
For **Ubuntu**:
113
93
114
-
```bash
94
+
```bash
115
95
$ sudo apt-get install libudunits2-dev
116
96
```
117
97
118
98
For **Fedora**:
119
99
120
-
```bash
100
+
```bash
121
101
$ sudo dnf install udunits2-devel
122
102
```
123
103
124
104
For **Arch**:
125
105
126
-
```bash
106
+
```bash
127
107
$ pacaur/yaourt/whatever -S udunits
128
108
```
129
109
130
110
For **Debian**:
131
111
132
-
```bash
112
+
```bash
133
113
$ sudo apt-get install -y libudunits2-dev
134
114
```
135
-
136
-
:::::::::::::::::::::::::
115
+
:::
137
116
138
117
### R
139
118
140
119
Participants who do not already have `R` installed should download and install it.
141
120
142
-
:::::::::::::::: spoiler
143
-
121
+
::: spoiler
144
122
## Windows
145
123
146
124
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".
125
+
:::
147
126
148
-
:::::::::::::::::::::::::
149
-
150
-
:::::::::::::::: spoiler
151
-
127
+
::: spoiler
152
128
## macOS
153
129
154
130
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`.
131
+
:::
155
132
156
-
:::::::::::::::::::::::::
157
-
158
-
:::::::::::::::: spoiler
159
-
133
+
::: spoiler
160
134
## Linux
161
135
162
136
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.
163
-
164
-
:::::::::::::::::::::::::
137
+
:::
165
138
166
139
### RStudio
167
140
@@ -171,29 +144,28 @@ RStudio is a GUI for using `R` that is available for Windows, macOS, and various
171
144
172
145
The following `R` packages are used in the various geospatial lessons.
@@ -222,24 +194,21 @@ This option involves downloading an Docker image that contains an installation o
222
194
223
195
Once up and running - you'll have full access to RStudio right from your browser:
224
196
225
-
{alt='RStudio layout in browser showing similarity to desktop layout'}
197
+
{alt="RStudio layout in browser showing similarity to desktop layout"}
226
198
227
199
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.
228
200
229
-
:::::::::::::::: spoiler
230
-
201
+
::: spoiler
231
202
## Downloading and Installing Docker Community Edition
232
203
233
204
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).
234
205
235
206
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.
236
207
237
208
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/).
209
+
:::
238
210
239
-
:::::::::::::::::::::::::
240
-
241
-
:::::::::::::::: spoiler
242
-
211
+
::: spoiler
243
212
## Using the `rocker/geospatial` Docker Image via the Command Line
244
213
245
214
#### Download and Set-up
@@ -248,23 +217,23 @@ Once Docker is installed and up and running, you will need to open your computer
248
217
249
218
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:
250
219
251
-
```bash
220
+
```bash
252
221
$ docker pull rocker/geospatial
253
222
```
254
223
255
224
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.
256
225
257
226
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).
264
233
265
234
The last step before launching your container in a browser is to identify the port that your Docker container is running in:
266
235
267
-
```bash
236
+
```bash
268
237
$ docker port gis
269
238
```
270
239
@@ -274,30 +243,28 @@ An output, for example, of `8787/tcp -> 0.0.0.0:32768` would indicate that you s
274
243
275
244
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:
276
245
277
-
```bash
246
+
```bash
278
247
$ docker stop gis
279
248
```
280
249
281
250
#### Re-starting a Container
282
251
283
252
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:
284
253
285
-
```bash
254
+
```bash
286
255
$ docker start gis
287
256
```
288
257
289
258
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:
290
259
291
-
```bash
260
+
```bash
292
261
$ docker ps -a
293
262
```
294
263
295
264
If you are returning to a session after stopping Docker itself, make sure Docker is running again before re-starting your container!
265
+
:::
296
266
297
-
:::::::::::::::::::::::::
298
-
299
-
:::::::::::::::: spoiler
300
-
267
+
::: spoiler
301
268
## Using the `rocker/geospatial` Docker Image via Kitematic
302
269
303
270
#### Download and Install Kitematic
@@ -308,17 +275,17 @@ If you are returning to a session after stopping Docker itself, make sure Docker
308
275
309
276
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.
310
277
311
-
278
+
312
279
313
280
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.
314
281
315
-
282
+
316
283
317
284
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.
318
285
319
286
When you are ready, copy the `Access URL` from the `Home` tab:
320
287
321
-
288
+
322
289
323
290
Paste that url into your browser and, if prompted, enter `rstudio` for both the username and the password.
324
291
@@ -327,37 +294,32 @@ Paste that url into your browser and, if prompted, enter `rstudio` for both the
327
294
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.
328
295
329
296
You can restart your container later by clicking the `Restart` button.
297
+
:::
330
298
331
-
:::::::::::::::::::::::::
332
-
333
-
:::::::::::::::: spoiler
334
-
299
+
::: spoiler
335
300
## Managing Docker Containers and Images
336
301
337
302
To obtain a list of all of your current Docker containers:
338
303
339
-
```bash
304
+
```bash
340
305
$ docker ps -a
341
306
```
342
307
343
308
To list all of the currently downloaded Docker images:
344
309
345
-
```bash
310
+
```bash
346
311
$ docker images -a
347
312
```
348
313
349
314
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`:
350
315
351
-
```bash
316
+
```bash
352
317
$ docker system prune
353
318
```
354
319
355
320
To remove **all** Docker resources, including currently named containers:
0 commit comments