…manage your workspace

Jun 7, 2023

1.3 …manage your workspace

We are going to be doing a lot of practical work throughout this book so it is worthwhile considering how we will manage our workspace.

A lot of this section will only make sense once you have read about the tools Git, VirtualBox, and Vagrant but I’m assembling basic advice here to make it easier to refer to later.

We need to control two working environments throughout this course:

The host workspace—this is the workspace on your computer, and the one we will set up shortly.
The guest workspace—this is the workspace on the VirtualBox virtual machines we will be creating. Generally you will find these already created on each virtual machine.

If you follow this book from page one to the end you should find your workspaces are always in sync with whatever the book is dealing with but practically many of you will jump to sections of particular interest, skipping many sections. Anticipating this I’ve put in plenty of checkpoints, particularly for the guest workspace.

1.3.1 Initial setup of your workspace

Assuming you have installed Git (see §2.4) you can create your project’s host workspace.

1mkdir sfs 
2cd sfs 
3git clone --depth 1 https://gitlab.com/saltyvagrant.classes/sfs-material.git course-material 
4mkdir classroom 
5mkdir archive

Your sfs workspace now contains three directories; course-material that holds all this books accompanying material, classroom is where you will follow along with the course, and archive is where we will store various backup files.

Throughout this book I use the WSR directory¹ to refer to the root of your workspace. Any path that does not explicitly start from the WSR root assumes you are following instructions from the last checkpoint and are relative to whichever directory you should be in at the time.

1cd WSR 
2cd WSR/classroom 
3cd ../course-material 
4cd WSR 
5cd classroom

Lines 1, 2, and 4 each start with WSR and are therefore not really relative to your current working directory. You should take these to be absolute directories rooted at your workspace root WSR. If your workspace is at /home/fred/xyz then WSR/classroom should be read as /home/fred/xyz/classroom.

Line 3 is relative to your current working directory (in this example WSR/classroom) and is referring to WSR/course-material (since the parent of WSR/classroom it WSR and course-material is to be found directly under this directory).

Line 5 is again relative to your current working directory. As you just moved to WSR (line 4) this refers to your classroom directory under that root.

1.3.2 Regular host workspace activities

There are a number of actions you may want to repeat throughout this course. Rather than repeat them in full each time I present them here and simply refer to these entries as necessary.

1.3.2.1 Checkpoint Classroom

You will need to checkpoint the classroom at least once, when you start the course. If you get lost in the material you can reset your classroom to one of the checkpoints in the book. This will clean up you classroom directory ensuring you are ready to proceed with the book’s follow-along lessons.

Shutdown any running classroom Virtual Machine (VM)² (if one is currently set up).
```
1cd WSR/classroom 
2vagrant halt
```
Backup your current classroom
```
1cd WSR 
2mv classroom archive/classroom_<date>
```
Replace <date> with the date of the backup (I recommend using a YYYMMDD format as this sorts properly). For example, if today where December 3^rd 2020 and I wanted to backup my classroom I would us the following³.
```
1cd WSR 
2mv classroom archive/classroom_20201203
```
Copy the relevant material from course-material
```
1cd WSR 
2cp course-material/<checkpoint>/ classroom
```
Replacing <checkpoint> with the name if the checkpoint from which you want to proceed.
Start up the classroom
```
1cd WSR/classroom 
2vagrant up
```
This will start up any VM required for the classes.

1.3.2.2 Snapshot Classroom

If you are following the advice given above and ‘playing’ with your classrooms then I suggest your take a snapshot of your environment just before you start to play. This way you can quickly reset your classroom back you a point where it is ready for you to continue following along with this course.

Follow along with this course.
Decide to ‘play’ for a while so take a snapshot.
```
1cd WSR/classroom 
2vagrant snapshot save class_<date>
```
Replace <date> with the date of the snapshot (I recommend using a YYMMDD format as this sorts properly). For example, if today where December 3^rd 2020 and I wanted to backup my classroom I would use the following.
```
1cd WSR/classroom 
2vagrant snapshot save class_201203
```
Play with your classroom environment.
Decide to resume the course as described in this book.
Restore your classroom to the saved snapshot.
```
1cd WSR/classroom 
2vagrant snapshot restore class_<date>
```
Where <date> is the date of the snapshot to be restored. For example, to restore the snapshot from December 3^rd 2020 we created earlier I would use the following.
```
1cd WSR/classroom 
2vagrant snapshot restore class_201203
```
Resume course.

One other useful snapshot command is list, this can be used to show your previously saved snapshots (useful if, like me, your forget this sort of thing).

1cd WSR/classroom 
2vagrant snapshot list

1.3.2.3 Update material

This book, and consequently the accompanying material, is continually being updated⁴. Most updates will be to the guest workspace consequently the host workspace will rarely need updating, the following procedure will update your host workspace and bring your guest systems up to date.

1cd WSR/course-material 
2git pull

This will update the course material in the host workspace. If you have created a classroom then you may need to re-copy the relevant course material and re-provision the virtual machine.

1cd WSR 
2cp -rf course-material/<checkpoint>/* classroom 
3cd classroom 
4vagrant up --provision

Line 2 copies the relevant checkpoint files (obviously replacing <checkpoint> with the actual checkpoint directory you want to use). Line 4 will update any guest virtual machines (even if they already exist or are running).

¹If you are using Microsoft Windows as your host you will need to convert ‘/‘ to ‘\‘ in paths whenever working in the host workspace. (It is precisely because of this sort of “conversion” nonsense that we use the guest workspace most of the time.)

²A segmented presentation or emulation of a physical computer allowing multiple ‘guest’ machines to share the physical resources of the ‘host’ computer.

³Windows users should use move rather than mv

⁴If you have downloaded the PDF version of this book then you should download the latest version at the same time you update the course material, otherwise they will get out of sync.