Before we can get started in class, you will need to set up a few things on your computer. If something goes wrong during the semester, you may need to repeat some of these steps. If you have any trouble while installing please reach out on the class slack workspace.

Setup Your git Repo

We will use git to manage code in this class. This will be the way that you submit solutions to assignments and receive class code from the instructor. This step only needs to be performed ONCE for the semester. You will use the same git repo for all assignments and labs (except possibly the final project).

These instructions are designed for use on github.com. They may work using other git services, but for simplicity, only instructions for GitHub are provided. Please let the instructor know if you use a service besides GitHub.

1. If you do not have one already, create an account on github.com 
2. A template is provided for you to create your own repo. GitHub has an easy way to create your own repo in the form of this template. Go to: https://github.com/UML-EECE-5560/eece5560-base and click the green “Use This Temple” button.
3. Name your repo using ONLY lowercase letters, numbers, and dashes. Make sure to set it to PRIVATE. You may name your repo whatever you like as long as it follows these requirements. Creating a private repo should be free. If GitHub tries to charge you, associate your university email address with your GitHub account and it should become an educational account.
4. Share the repository with the instructor, username: paulrobinette

Now you have a place to store your code for the semester that only you and the instructor can see.

Installing Linux

It is highly recommended to use Linux in this class to complete the homework assignments and develop on the robot. Both Ubuntu 22.04 and Ubuntu 20.04 are supported by the current version of Duckietown software. Either should work, but the instructions in this guide assumes you are using Ubuntu 20.04. If your computer cannot support this, please reach out to the instructor. The only reason this step will need to be rerun is if your Linux install becomes corrupted (unlikely).

1. First, you need to choose if you would like to run Linux by itself, as a dual boot system, or as a virtual machine (VM). Refer to the lecture to understand the difference.
2. Regardless of your chosen install method, please ensure that you have at least 2GB of RAM and 60GB of hard drive space available. You will need to allocate about 60GB of space to the Linux install regardless of method.
3. If installing in a VM, there are guides for most of the major VM programs.
   1. VirtualBox (free option): https://linuxhint.com/install_ubuntu_virtualbox_2004/
      Make sure you install the guest additions package!
   2. VMWare Workstation: https://ubuntu.tutorials24x7.com/blog/how-to-install-ubuntu-20-04-lts-on-windows-using-vmware-workstation-player
4. If dual booting instead: this can be a little trickier but is still pretty easy. Tutorials are available for both Windows and MacOS base systems.
   1. Installing on a USB drive: https://linuxhint.com/run_ubuntu_usb_stick/
   2. Windows: https://linuxconfig.org/how-to-install-ubuntu-20-04-alongside-windows-10-dual-boot
   3. MacOS (somewhat difficult): https://linuxnewbieguide.org/how-to-install-linux-on-a-macintosh-computer/

Regardless of the method you chose, you should now have a Linux install ready to continue. This is a good time to work on a tutorial if you are unfamiliar with the Linux command line: https://ryanstutorials.net/linuxtutorial/

Setup Your Docker Workflow

The following commands are intended to be run from a Linux command-line terminal. Commands are tested in Ubuntu 18.04 and may need minor modifications to run in Ubuntu 20.04.

1. Install docker on your system:

   $ sudo apt install docker.io

   You should only need to do this once on a Linux system.

2. Add your username to the docker group:

   $ sudo usermod -aG docker ${USER}

3. Install Duckietown Shell (dts). We will talk about this more in class when setting up the robots, but we are going to take advantage of a few features here to make setting up your laptop easier. Run these commands:

   $ sudo apt install -y python3-pip git git-lfs
   
   $ pip3 install --no-cache-dir --user -U duckietown-shell

   NOTES:

   1. NEVER use sudo to install dts! In general, never use sudo with pip3 at all.
   2. dts documentation: https://github.com/duckietown/duckietown-shell
   3. dts can be installed on MacOS as well with most features supported. Windows is not supported but may work.
   4. dts will likely need to be updated throughout the semester as changes are released. Rerun the pip3 command above whenever it needs to be updated.
4. Reboot Linux (if in a virtual machine, only the VM needs to be rebooted)
5. Set the dts version:

   $ dts --set-version daffy

   (If you see a prompt that looks like (Cmd) here then type exit to leave dts)

6. Run the following command to verify Docker is set up correctly:

   $ docker run hello-world

   You should see the following output:

   Hello from Docker!

   This message shows that your installation appears to be working correctly.
   If not, rerun steps 2 and 4.

7. You may also want to set up an account on Docker Hub so that downloads are not throttled: https://docs.duckietown.com/daffy/opmanual-duckiebot/setup/setup_account/docker_accounts.html

Setup Your git Repo

1. Before we clone your git repo, we need to setup ssh keys. This is a requirement for connecting to GitHub from your laptop.
   1. First, generate an ssh key on your Linux system if you have not already. Run this command in your terminal:

      $ ssh-keygen

      For more info, see this tutorial: https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-20-04

   2. Next, get your PUBLIC key. Use this command, but replace the filename if you used anything besides the default name when generating:

      $ cat ~/.ssh/id_rsa.pub

   3. Finally, copy your public key into your GitHub account. Click on your user icon in the upper right, click settings, then select SSH and GPG Keys on the left hand side. Click New SSH Key, name it, and copy the key from the previous step here. Click Add SSH Key and move to the next step.
   4. For more info, check out this tutorial: https://www.inmotionhosting.com/support/server/ssh/how-to-add-ssh-keys-to-your-github-account/
2. Now, we need to clone your git repo. You can find your repo URL on the top right of the page on GitHub. Click the green “Code” button, click the “ssh” tab and copy that URL, then run:

   
   $ git clone <repo_url>

   Note that this will clone your repo into your current folder as a new folder with whatever name you gave your repo on GitHub. You may need to clone your repo a few times in class. It is fairly easy to break your local copy, but it is even easier to download a fresh copy from GitHub and try again! Just run the clone command again.

3. If you have not used git before on this system, setup your name and email address:

   $ git config --global user.name "<your-name>"
   $ git config --global user.email "<your-email>"

4. Change directory to your git repo:

   cd <your-git-repo-directory>

5. We need to edit lines 2-4 in the “Dockerfile” here. All we want to do is update these lines with the name of your repo, your information, and a description. Note that this only needs to be done the first time you clone your repo or after you update to a new version of the template (this will be in another guide). The easiest way to edit the file is using gedit:

   $ gedit Dockerfile

6. Now we need to commit and push our changes. First, let’s make sure git realizes we changed something:

   $ git status

   You should see that Dockerfile has changed.

7. Now we need to tell git to add this file to the next commit:

   $ git add Dockerfile

8. Then we will run the commit, including a short message that logs what we did:

   $ git commit -m "updated dockerfile"

   It is always a good idea to use a descriptive log message (the part in quotes after -m) so you keep track of when you made what changes. You can put whatever text you want inside the quotes.

9. Now we need to push this to GitHub:

   $ git push origin master

   If you check your GitHub page after this step you should see a new commit with these changes to the Dockerfile.

Now you should be ready to proceed with assignments.