Skip to content

Commit a1c7438

Browse files
trevorcampbelltrevorcampbell
committed
reorder windows/mac/ubuntu and other ttimbers review suggestions
1 parent 3f4392b commit a1c7438

File tree

1 file changed

+127
-100
lines changed

1 file changed

+127
-100
lines changed

‎source/setup.Rmd

Lines changed: 127 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -63,73 +63,33 @@ a pre-built *container* that comes with precisely the right versions of
6363
all software packages needed run the worksheets that come with this book.
6464
\index{Docker}
6565

66-
### Ubuntu
67-
68-
**Installation** To install Docker on Ubuntu, open the terminal and enter the following five commands.
69-
```
70-
sudo apt update
71-
sudo apt install ca-certificates curl gnupg
72-
curl -fsSL https://get.docker.com -o get-docker.sh
73-
sudo chmod u+x get-docker.sh
74-
sudo sh get-docker.sh
75-
```
76-
77-
**Running JupyterLab** In the terminal, navigate to the directory where you want to run JupyterLab, and run
78-
the following command.
79-
```
80-
docker run --rm -v $(pwd):/home/jovyan/work -p 8888:8888 ubcdsci/r-dsci-100:20230724142640d8f06f jupyter lab
81-
```
82-
The terminal will then print some text as the Docker container starts. Once the text stops scrolling, find the
83-
URL in your terminal that starts with `http://127.0.0.1:8888` (highlighted by the red box Figure \@ref(fig:ubuntu-docker-terminal)), and paste it into your browser to start JupyterLab.
84-
85-
```{r ubuntu-docker-terminal, echo = FALSE, fig.cap = "The terminal text after running the Docker container in Ubuntu. The red box indicates the URL that you should paste into your browser to open JupyterLab.", fig.retina = 2, out.width="100%"}
86-
image_read("img/setup/ubuntu-docker.png") |>
87-
image_crop("3632x2000")
88-
```
89-
90-
More information on installing and running Docker on Ubuntu, as well as troubleshooting tips, can be found
91-
[in the online Docker documentation](https://docs.docker.com/engine/install/ubuntu/).
92-
93-
### MacOS
94-
95-
**Installation** To install Docker on MacOS,
96-
visit [the online Docker documentation](https://docs.docker.com/desktop/install/mac-install/), and
97-
download the `Docker.dmg` installation file that is appropriate for your
98-
computer. To know which installer is right for your machine, you need to know
99-
whether your computer has an Intel processor (older machines) or an
100-
Apple processor (newer machines); the [Apple support page](https://support.apple.com/en-ca/HT211814) has
101-
information to help you determine which processor you have. Once downloaded, double-click
102-
the file to open the installer, then drag the Docker icon to the Applications folder.
103-
Double-click the icon in the Applications folder to start Docker. In the installation
104-
window, use the recommended settings.
105-
106-
**Running JupyterLab** Once Docker is installed and running, follow the
107-
instructions below in the Windows section on *Running JupyterLab* (the user
108-
interface is the same). More information on installing and running Docker on
109-
MacOS, as well as troubleshooting tips, can be
110-
found [in the online Docker documentation](https://docs.docker.com/desktop/install/mac-install/).
66+
> **Note:** A *container* is a virtualized user space within your computer.
67+
> Within the container, you can run software in isolation without interfering with the
68+
> other software that already exists on your machine. In this book, we use
69+
> a container to run a specific version of the R programming
70+
> language, as well as other necessary packages. The container ensures that
71+
> the worksheets function correctly, even if you have a different version of R
72+
> installed on your computer—or even if you haven't installed R at all!
11173
11274
### Windows
11375

114-
**Installation** To install Docker on Windows, visit [the online Docker documentation](https://docs.docker.com/desktop/install/windows-install/),
76+
**Installation** To install Docker on Windows,
77+
visit [the online Docker documentation](https://docs.docker.com/desktop/install/windows-install/),
11578
and download the `Docker Desktop Installer.exe` file. Double-click the file to open the installer
11679
and follow the instructions on the installation wizard, choosing **WSL-2** instead of **Hyper-V** when prompted.
11780

118-
Occasionally, when you first run Docker on Windows, you will encounter an error message. Some common errors you may see:
119-
120-
- If you need to update WSL, you can enter `cmd.exe` in the Start menu to run the command line. Type `wsl --update` to update WSL.
121-
- If the admin account on your computer is different to your user account, you must add the user to the "docker-users" group.
122-
Run Computer Management as an administrator and navigate to `Local Users` and `Groups -> Groups -> docker-users`. Right-click to
123-
add the user to the group. Log out and log back in for the changes to take effect.
124-
- If you need to enable virtualization, you will need to edit your BIOS. Restart your computer, and enter the BIOS using the hotkey
125-
(usually Delete, Esc, and/or one of the F# keys). Look for an "Advanced" menu, and under your CPU settings, set the "Virtualization" option
126-
to "enabled". Then save the changes and reboot your machine. If you are not familiar with BIOS editing, you may want to find an expert
127-
to help you with this, as editing the BIOS can be dangerous. Detailed instructions for doing this are beyond the scope of this book.
128-
More information on installing and running
129-
Docker on Windows, as well as troubleshooting tips, can be found [in the online
130-
Docker documentation](https://docs.docker.com/desktop/install/windows-install/).
131-
132-
**Running JupyterLab** Once Docker is running (in either Windows or MacOS), you need to download and run the
81+
> **Note:** Occasionally, when you first run Docker on Windows, you will encounter an error message. Some common errors you may see:
82+
>
83+
> - If you need to update WSL, you can enter `cmd.exe` in the Start menu to run the command line. Type `wsl --update` to update WSL.
84+
> - If the admin account on your computer is different to your user account, you must add the user to the "docker-users" group.
85+
> Run Computer Management as an administrator and navigate to `Local Users` and `Groups -> Groups -> docker-users`. Right-click to
86+
> add the user to the group. Log out and log back in for the changes to take effect.
87+
> - If you need to enable virtualization, you will need to edit your BIOS. Restart your computer, and enter the BIOS using the hotkey
88+
> (usually Delete, Esc, and/or one of the F# keys). Look for an "Advanced" menu, and under your CPU settings, set the "Virtualization" option
89+
> to "enabled". Then save the changes and reboot your machine. If you are not familiar with BIOS editing, you may want to find an expert
90+
> to help you with this, as editing the BIOS can be dangerous. Detailed instructions for doing this are beyond the scope of this book.
91+
92+
**Running JupyterLab** Run Docker Desktop. Once it is running, you need to download and run the
13393
Docker *image* that we have made available for the worksheets (an *image* is like a "snapshot" of a
13494
computer with all the right packages pre-installed). In the search bar, enter `ubcdsci/r-dsci-100`, as this is
13595
the name of the image. You will be presented
@@ -142,17 +102,22 @@ image_read("img/setup/docker-1.png") |>
142102
image_crop("3632x2000")
143103
```
144104

145-
Once the image is done downloading, click the "Images" button on the left side of the Docker Desktop window (Figure \@ref(fig:docker-desktop-images)). You
105+
Once the image is done downloading, click the "Images" button on the left side
106+
of the Docker Desktop window (Figure \@ref(fig:docker-desktop-images)). You
146107
will see the recently downloaded image listed there under the "Local" tab.
147108

148109
```{r docker-desktop-images, echo = FALSE, fig.cap = "The Docker Desktop images tab.", fig.retina = 2, out.width="100%"}
149110
image_read("img/setup/docker-2.png") |>
150111
image_crop("3632x2000")
151112
```
152113

153-
To start up a *container* using that image, click the play button beside the image. This will open the run configuration menu (Figure \@ref(fig:docker-desktop-runconfig)).
154-
In the "Host port" textbox, enter `8888`. In the "Volumes" section, click the "Host path" box and navigate to the folder where your Jupyter worksheets
155-
are stored. In the "Container path" text box, enter `/home/jovyan/work`. Then click the "Run" button to start the container.
114+
To start up a *container* using that image, click the play button beside the
115+
image. This will open the run configuration menu (Figure \@ref(fig:docker-desktop-runconfig)).
116+
Expand the "Optional settings" drop down menu. In the "Host port" textbox, enter
117+
`8888`. In the "Volumes" section, click the "Host path" box and navigate to the
118+
folder where your Jupyter worksheets are stored. In the "Container path" text
119+
box, enter `/home/jovyan/work`. Then click the "Run" button to start the
120+
container.
156121

157122
```{r docker-desktop-runconfig, echo = FALSE, fig.cap = "The Docker Desktop container run configuration menu.", fig.retina = 2, out.width="100%"}
158123
image_read("img/setup/docker-3.png") |>
@@ -165,10 +130,67 @@ URL in the terminal that starts
165130
with `http://127.0.0.1:8888` (highlighted by the red box in Figure \@ref(fig:ubuntu-docker-terminal)), and paste it
166131
into your browser to start JupyterLab.
167132

168-
```{r docker-desktop-url, echo = FALSE, fig.cap = "The terminal text after running the Docker container in Ubuntu. The red box indicates the URL that you should paste into your browser to open JupyterLab.", fig.retina = 2, out.width="100%"}
133+
134+
```{r docker-desktop-url, echo = FALSE, fig.cap = "The terminal text after running the Docker container. The red box indicates the URL that you should paste into your browser to open JupyterLab.", fig.retina = 2, out.width="100%"}
169135
image_read("img/setup/docker-4.png") |>
170136
image_crop("3632x2000")
171137
```
138+
When you are done working, make sure to shut down and remove the container by
139+
clicking the red trash can symbol (in the top right corner of Figure \@ref(fig:ubuntu-docker-terminal)).
140+
You will not be able to start the container again until you do so.
141+
More information on installing and running
142+
Docker on Windows, as well as troubleshooting tips, can
143+
be found in [the online Docker documentation](https://docs.docker.com/desktop/install/windows-install/).
144+
145+
### MacOS
146+
147+
**Installation** To install Docker on MacOS,
148+
visit [the online Docker documentation](https://docs.docker.com/desktop/install/mac-install/), and
149+
download the `Docker.dmg` installation file that is appropriate for your
150+
computer. To know which installer is right for your machine, you need to know
151+
whether your computer has an Intel processor (older machines) or an
152+
Apple processor (newer machines); the [Apple support page](https://support.apple.com/en-ca/HT211814) has
153+
information to help you determine which processor you have. Once downloaded, double-click
154+
the file to open the installer, then drag the Docker icon to the Applications folder.
155+
Double-click the icon in the Applications folder to start Docker. In the installation
156+
window, use the recommended settings.
157+
158+
**Running JupyterLab** Run Docker Desktop. Once it is running, follow the
159+
instructions above in the Windows section on *Running JupyterLab* (the user
160+
interface is the same). More information on installing and running Docker on
161+
MacOS, as well as troubleshooting tips, can be
162+
found in [the online Docker documentation](https://docs.docker.com/desktop/install/mac-install/).
163+
164+
### Ubuntu
165+
166+
**Installation** To install Docker on Ubuntu, open the terminal and enter the following five commands.
167+
```
168+
sudo apt update
169+
sudo apt install ca-certificates curl gnupg
170+
curl -fsSL https://get.docker.com -o get-docker.sh
171+
sudo chmod u+x get-docker.sh
172+
sudo sh get-docker.sh
173+
```
174+
175+
**Running JupyterLab** In the terminal, navigate to the directory where you want to run JupyterLab, and run
176+
the following command.
177+
```
178+
docker run --rm -v $(pwd):/home/jovyan/work -p 8888:8888 ubcdsci/r-dsci-100:20230724142640d8f06f jupyter lab
179+
```
180+
The terminal will then print some text as the Docker container starts. Once the text stops scrolling, find the
181+
URL in your terminal that starts with `http://127.0.0.1:8888` (highlighted by the
182+
red box Figure \@ref(fig:ubuntu-docker-terminal)), and paste it into your browser to start JupyterLab.
183+
More information on installing and running Docker on Ubuntu, as well as troubleshooting tips, can be found in
184+
[the online Docker documentation](https://docs.docker.com/engine/install/ubuntu/).
185+
186+
187+
```{r ubuntu-docker-terminal, echo = FALSE, fig.cap = "The terminal text after running the Docker container in Ubuntu. The red box indicates the URL that you should paste into your browser to open JupyterLab.", fig.retina = 2, out.width="100%"}
188+
image_read("img/setup/ubuntu-docker.png") |>
189+
image_crop("3632x2000")
190+
```
191+
192+
193+
172194

173195
## Working with JupyterLab Desktop
174196

@@ -180,28 +202,24 @@ that require expert troubleshooting. The downside of JupyterLab Desktop is that
180202
you may not end up with the right versions of all the R packages needed for the worksheets. Docker, on the other hand,
181203
*guarantees* that the worksheets will work exactly as intended.
182204

183-
In this section, we will cover how to install Git (for version control, as discussed in Chapter \@ref(Getting-started-with-version-control)),
184-
JupyterLab Desktop, the JupyterLab Git extension, and all of the R packages needed to run the code in this book.
205+
In this section, we will cover how to install JupyterLab Desktop,
206+
Git and the JupyterLab Git extension (for version control, as discussed in Chapter \@ref(Getting-started-with-version-control)), and
207+
all of the R packages needed to run
208+
the code in this book.
185209
\index{git!installation}\index{JupyterLab Desktop}
186210

187-
### Ubuntu
211+
### Windows
188212

189213
**Installation** First, we will install Git for version control.
190-
Open the terminal and type the following commands:
191-
```
192-
sudo apt update
193-
sudo apt install git
194-
```
214+
Go to [the Git download page](https://git-scm.com/download/win) and
215+
download the Windows version of Git. Once the download has finished, run the installer and accept
216+
the default configuration for all pages.
195217
Next, visit the ["Installation" section of the JupyterLab Desktop homepage](https://github.com/jupyterlab/jupyterlab-desktop#installation).
196-
Download the `JupyterLab-Setup-Debian.deb` installer file for Ubuntu/Debian.
197-
Open a terminal, navigate to where the installer file was downloaded, and run the command
198-
```
199-
sudo dpkg -i JupyterLab-Setup-Debian.deb
200-
```
201-
Run JupyterLab Desktop using the command
202-
```
203-
jlab
204-
```
218+
Download the `JupyterLab-Setup-Windows.exe` installer file for Windows.
219+
Double-click the installer to run it, use the default settings.
220+
Run JupyterLab Desktop by clicking the icon on your desktop.
221+
222+
205223
**Configuring JupyterLab Desktop**
206224
Next, in the JupyterLab Desktop graphical interface that appears (Figure \@ref(fig:setup-jlab-gui)),
207225
you will see text at the bottom saying "Python environment not found". Click "Install using the bundled installer"
@@ -234,22 +252,6 @@ JupyterLab Desktop entirely before you proceed to doing your data analysis.
234252
This will ensure all the software and settings you put in place are
235253
correctly set up and ready for use.
236254

237-
### Windows
238-
239-
**Installation** First, we will install Git for version control.
240-
Go to [the Git download page](https://git-scm.com/download/win) and
241-
download the Windows version of Git. Once the download has finished, run the installer and accept
242-
the default configuration for all pages.
243-
Next, visit the ["Installation" section of the JupyterLab Desktop homepage](https://github.com/jupyterlab/jupyterlab-desktop#installation).
244-
Download the `JupyterLab-Setup-Windows.exe` installer file for Windows.
245-
Double-click the installer to run it, use the default settings.
246-
Run JupyterLab Desktop by clicking the icon on your desktop.
247-
248-
**Configuring JupyterLab Desktop** From this point onward, with JupyterLab Desktop running,
249-
follow the instructions in the Ubuntu section on *Configuring JupyterLab Desktop* to set up the
250-
environment, install the JupyterLab Git extension, and install
251-
the various R software packages needed for the worksheets.
252-
253255

254256
### MacOS
255257

@@ -271,7 +273,32 @@ the JupyterLab Desktop icon to the Applications folder. Double-click
271273
the icon in the Applications folder to start JupyterLab Desktop.
272274

273275
**Configuring JupyterLab Desktop** From this point onward, with JupyterLab Desktop running,
274-
follow the instructions in the Ubuntu section on *Configuring JupyterLab Desktop* to set up the
276+
follow the instructions in the Windows section on *Configuring JupyterLab Desktop* to set up the
275277
environment, install the JupyterLab Git extension, and install
276278
the various R software packages needed for the worksheets.
277279

280+
### Ubuntu
281+
282+
**Installation** First, we will install Git for version control.
283+
Open the terminal and type the following commands:
284+
```
285+
sudo apt update
286+
sudo apt install git
287+
```
288+
Next, visit the ["Installation" section of the JupyterLab Desktop homepage](https://github.com/jupyterlab/jupyterlab-desktop#installation).
289+
Download the `JupyterLab-Setup-Debian.deb` installer file for Ubuntu/Debian.
290+
Open a terminal, navigate to where the installer file was downloaded, and run the command
291+
```
292+
sudo dpkg -i JupyterLab-Setup-Debian.deb
293+
```
294+
Run JupyterLab Desktop using the command
295+
```
296+
jlab
297+
```
298+
299+
**Configuring JupyterLab Desktop** From this point onward, with JupyterLab Desktop running,
300+
follow the instructions in the Windows section on *Configuring JupyterLab Desktop* to set up the
301+
environment, install the JupyterLab Git extension, and install
302+
the various R software packages needed for the worksheets.
303+
304+

0 commit comments

Comments
 (0)