Computational Setup

Computational Setup #

Note: These steps take time! Read the instructions in advance, and don’t wait until the last minute.

This guide walks you through the steps necessary to set up your computer for the work you will do in this course. Once you have completed this setup, you should have all of the software tools you need to complete the worksheets and projects in this course.

We have split each step into a Context section that explains what you are doing and why, a Directions section that explains what to do, and a Check section with instructions for you to test that you have completed the step successfully. Reading the Context section is optional - it simply explains why you are doing each step.

The setup has quite a few steps and may appear daunting at first. We ask that you try to follow these instructions as closely as you can, because we have done quite a bit of testing with these instructions and have confirmed that they work reasonably well for most student setups. If you run into any issues and need our help, it will be very helpful for us to know if and how you did anything differently from what these instructions specify. We are happy to provide help if you get stuck, so please do not hesitate to ask!

Install Linux as a Virtual Machine #

Context #

A virtual machine (VM) is exactly what it sounds like - a virtual computer inside your computer. VMs are useful tools for software developers. Individual computers can have a variety of settings and software that make them unique, and these differences can cause problems with software. It is helpful to have everyone on a team test software on a consistent setup with the same settings, which a VM is well-suited for. You can probably see why the instructors like using VMs in this course - we want all students to be working in the same computing environment. This makes your software more likely to work, and makes troubleshooting easier.

Directions #

If you have macOS Big Sur, VirtualBox will likely not work. Use VMWare Fusion instead of VirtualBox, which has been reported to work.

To get this VM up and running, you will first need to download and install VirtualBox. VirtualBox is a program that will load and run the VM. Read the instructions carefully. You want to click on the link below the header “VirtualBox 6.1.16 platform packages” that corresponds with the operating system currently on your computer. For most of you, that will be the link “Windows hosts.”

You will also need to download the VM image file. An image file is basically a summary of all the settings and state of a computer system, stored as a single file. This is the information that lets everyone have the same VM. You can get the image file here. Please note that this image file is large (5.8 GB) so you will need the necessary disk space, as well as a stable (and preferably fast) Internet connection.

To get things set up, open VirtualBox. Select File -> Import Appliance. From there, select the .ova file you just downloaded and proceed with the import. You can use the default appliance settings.

Check #

Once you have done this, you should be able to start up the VM by clicking the green arrow labeled Start. The password for the user account is Python 3! (note the space in the middle).

Create a GitHub account #

Context #

Git is a distributed version control system: there is no “master copy” of your code history, so each copy stands on its own. To share your code with others, it’s helpful to use a hosting service that stores an online copy of your code and its history. (The copy does not necessarily have to be publicly accessible, though this is often the reason for hosting your code online.) For this purpose, we will use GitHub. In this step, you will create a GitHub account.

Directions #

If you don’t already have a GitHub account, go to https://github.com and create an account. Feel free to use any email address you want (or create one just for this account), but remember which email address you use, as you will need it when configuring Git on your computer (which is a later step in this guide). Your username does not have to be related to your actual name at all. That being said, like most usernames, it will be publicly visible, so if you plan on sharing code with the world, make sure you choose a username that you would be comfortable with others seeing.

Check #

To test that you have correctly set up your GitHub account, go to https://github.com/username, replacing username with the username you created. You should see a profile page for your username. If you get a 404 page, you may not have completed the account creation process.

You may also want to check that you can log into your account.

Configure Git #

Context #

Good code is designed to be maintained: edited and improved over time. To track the history of revisions and to submit work in this course, we will use a version control system called Git. You need to configure Git by setting your name and email address so that services like GitHub can properly attribute your work to your account.

If you try to do other operations in Git without having set up your name and email, you will see a message that starts with something like *** Please tell me who you are. and whatever operation you were trying to do will fail.

Directions #

To set your name in Git, first start Ubuntu in VirtualBox and log in. Then, open the Terminal application through the start menu (pressing the Windows key and typing in “Terminal”) or by simply pressing Ctrl-Alt-T. (Also note that in most VirtualBox versions, the right Ctrl key will not work, as it’s used for different functionality in VirtualBox.)

Once you have the Terminal open, you can run commands by typing text into the prompt you see and pressing Enter. Run the command git config --global user.name "Alan Turing", substituting your name for Alan Turing (but leaving the quotes in place). This can be any name you want, though you should probably avoid using a name that may be seen an attempt to impersonate someone else (e.g., “Bill Gates”).

To set your email, run git config --global user.email "alan@turing.org", substituting your GitHub email address for alan@turing.org. It’s important that your email match the one that GitHub has, because a mismatch can make Git fail in unintuitive ways.

If you mistyped your name or email, you can run the same command again with the correct name/email to fix the typo. If you mistyped user.name or user.email in the commands, you can use git config --unset user.naem (replacing user.naem with whatever you mistyped earlier) to remove that setting.

Check #

You can check that this process was successful by running git config --list. If you see lines starting with user.name and user.email with the values you expect, then the process was successful. You may see other parts of your configuration, but you can ignore these.

Add an SSH key to GitHub (Optional) #

This section is optional because it primarily adds a single convenience feature: not having to enter your GitHub username and password when performing certain operations in Git. We will gloss over much of the technical details of what this process actually does, instead focusing on how to get this working on your computer. In a nutshell, adding an SSH (Secure Shell) key to your GitHub account involves creating a special credential on your computer that provides an alternate way of authenticating you to GitHub. In cryptography, this credential is called a public key. The process consists of two steps: creating the key on your computer, and telling GitHub what this key is.

To create the key, open Terminal and run the command ssh-keygen -t ecdsa. You will be presented with a series of prompts; unless you know what changing these prompts will do, you should use the default settings (just hit Enter) for all of them. (In this case, it is fine to use a completely blank passphrase for this process.) This will create two files id_ecdsa and id_ecdsa.pub. Never share the contents of id_ecdsa with anyone. Doing so after you have added the key to GitHub will allow whomever you share the file with to authenticate to GitHub as you with no password necessary.

To add the key to GitHub, log into your account on GitHub. Click on your profile picture in the upper-right corner of the page and select Settings. Click on “SSH and GPG keys”, and then click on the “New SSH key” button to get a form you can fill with the details of your key. For “Title”, use a name that will help you remember the computer that you are currently setting up. For “Key”, start Ubuntu and run cat .ssh/id_ecdsa.pub, copying the resulting text that appears and pasting this into the field. When submitting this form, you will likely be asked to reconfirm your GitHub password.

Once you have set up your key as described above, you can clone (download) a code repository to your computer with a different link which will free you from entering your username and password when working with the repository. As an example, if you visit the repository https://github.com/twbs/bootstrap, you will see a green button in the upper-right area of the page that says “Clone or download”, and if you click on it, you will likely see a box that says “Clone with HTTPS”. You can click on the “Use SSH” link in the upper-right corner of this box, and the link in the box will change. You can use this new link in place of the standard HTTPS link in any Git command.

Bonus #

Since you read all the way to the end of this page (or maybe you just skipped down using the table of contents, but whatever), here’s a fun Python-related XKCD:

XKCD 1987: Python
Environment

Source: https://xkcd.com/1987/