Student Setup Guide
Follow this guide to get the curriculum up and running on your machine. Unfortunately, configuration and setup can often be different on everyone’s computer. We’ve done our best to include the necessary steps to get the curriculum up and running, But if you encounter a problem getting started, please raise an issue.
We recommend you install Visual Studio Code as your primary code editor for this course. https://code.visualstudio.com/
DockYard Academy is built using Livebook, which allows you to run Elixir Notebooks. Follow the Livebook Installation Guide to install Livebook Desktop or Livebook using Escripts if you prefer using the command line or are a Linux user.
You will need to use the command line to install livebook and elixir to run the curriculum on your computer. The command line is a text-based way of interacting with your computer.
The command line differs depending on your operating system.
- Windows: Search for Use the Command Prompt or the Powershell program. Generally, run in administrator mode to avoid permission issues. If you don't have a specific preference, then use Powershell.
- Mac or Linux: Use the Terminal app.
You can use the cd command to navigate your file system. You will need to navigate to specific folders in the instructions below.
cd path/to/file
Follow the latest Elixir Installation Guide to install Elixir on your computer.
To run this project, you need to create a version of the project that you control and own. This version is called a fork or forked repository.
flowchart LR
DY[DockYard Academy Repository]
F[Forked Repository]
DY --fork--> F
You can create a fork by pressing the fork button in the top right corner of the GitHub repository or click this link to create a fork
The forked repository is stored remotely on GitHub, so you need to download the codebase onto your local computer. We call this process cloning because we're downloading a copy (a clone) of the remote repository onto our local computer.
flowchart
R[Remote Repository]
L[Local Repository]
R --clone--> L
To do this, press the green CODE button on your forked repository and copy the URL provided.
Then run the following command in the command line from the folder you want to create your beta_curriculum folder in.
git clone URL
This should create a local copy of the project on your computer.
Git repositories use multiple branches to keep track of changes you make to the codebase.
Branches typically branch off of the main branch, which holds the main version of the codebase.
In general, you want to avoid creating changes directly on the main branch and instead create new branches to make your changes on.
flowchart BT
m[main]
b1[branch]
b2[branch]
b3[branch]
m --> b1
m --> b2
m --> b3
Create a solutions branch. This is where you will store exercise solutions.
Go to the project folder in your command line and run the following command.
You may name your branch solutions or pick any name you like. Simply replace solutions below with your desired branch name.
git checkout -b solutions
Now you can work on solutions and exercises.
Run the following in the project folder in your command line.
livebook server start.livemd
Or, if you are using Livebook Desktop start the program using the Livebook Desktop Shortcut and use the file explorer to navigate to the beta_curriculum folder, then open the start.livemd file.
You should see the Course Outline page, where you can find the reading materials and exercises for the course.
If we make significant changes to main you may want to update your fork to use the latest changes.
Click the Sync Fork button from your forked repository on GitHub.
Once you have the latest changes on your remote repository, you need to download them to your local repository. We call this process pulling.
flowchart TB
R[Remote Repository]
L[Local Repository]
R --pull changes--> L
Changes must be pulled to your main branch on your local repository, so ensure you are on this branch by running the following from your command line in the beta_curriculum folder.
git checkout main
Then run the following command from your command line in the beta_curriculum folder to pull the latest changes.
git pull
We recommend doing this regularly as we make significant changes daily.
If you are running the project with Livebook, make sure you completely stop the Livebook project either by stopping it from the command line or closing the Desktop Application.
While in beta, we will make significant (possibly breaking) changes that may not merge nicely into your existing solutions branch. To get around this issue, we recommend you create a new solutions branch after updating. This way, you can save your old changes on the old solutions branch, but not deal with potential merge conflicts.
Run the following in the command line from the beta_curriculum folder while on the main branch after updating to create a new solutions branch.
You may choose any non-existing solutions branch name. For example, you might decide to name your solutions branch based on the current date i.e. 2022-09-30-solutions.
git checkout -b 2022-09-30-solutions