Version Control - Fab Academy 2021 Recitations

### Recitation

_Monday January 27th, 2025_

# Version control & GitLab

**Presented by Julian Gallimore**

---

# Agenda

1. [Fabcloud services & How to login](#chapter-fabcloud)

1. [About GitLab CI](#chapter-gitlab-ci)

1. [Setup your local environment](#chapter-git-setup)

1. [Git pushing changes](#chapter-git-push)

1. [Setup mkdocs framework](#chapter-setup-mkdocs)

---
layout: true

**Fab Cloud platform**

---
name: chapter-fabcloud

# .logo_tiny[![](images/fabcloud_logo.png)] FABCLOUD

* [fablabs.io](https://fablabs.io) - Network map of FabLabs & Single Signon (universal logins)
* [gitlab.fabcloud.org](https://gitlab.fabcloud.org/) (self-hosted) - Git repository & website hosting
* [chat.academany.org](https://chat.academany.org/): self-hosted collaborative chat service
* [nueval.academany.org](https://nueval.academany.org/): Student evaluation tool

_FYI: All self-hosted by Fab Foundation (so we secure the data)_

---

## Fablabs.io

- Online platform that maps the FabLab network world-wide
- Discussion Forums for engaging with the wider FabLab network
- Provides the user account logins for our platforms GitLab & Nueval
    ie. a "Login with Fablabs.io" button

.logo_small.center[
	![Fabcloud Gitlab login screenshot](images/gitlab-login.png)
]

---

## What is GitLab

GitLab is a web-based tool that provides a Git-repository hosting plus extra features, developed by GitLab Inc.

* Similar to GitHub, Bitbucket
* Source code hosting your Git projects, plus:
  * Issues tracker
  * Collaboration tools (ie. Merge requests, Review apps, etc)
  * Website hosting (GitLab Pages)
  * CI pipeline for automatic project building/compiling
* We self-host our own version of Gitlab
  * We host all the Git repositories related to the academies
  * Where you will can edit YOUR documentation website

> More info about GitLab https://docs.gitlab.com/

---
layout: true

# GITLAB

---
class: center

## HOW TO LOGIN

Follow along with me with me

.caption[
  **New students**, find your access details in your email, subject:
  <br> "_Fab Academy 2025 accounts access_"
]

---
class: center

## 1. Start at GITLAB.fabcloud.org

---
class: center

## 2. Login at FABLABS.io

<img src="images/fablabs-login.jpg" width="300" />
.caption[
  Use your username/password we provided. Use "Forgot password" if you have trouble. 
  <br>_Do not create a new account, contact coordination instead_
]

---
class: center

## 4. (first time) Grant access to GitLab

---
class: center

## 5. Success! GITLAB Dashboard
You should be redirected to gitlab.fabcloud.org and see your project list

---

## What do we use Gitlab for

We use GitLab for all the content related to Fab Academy.

1. **Student repository** storing your documentation files

1. Use the GitLab tools to help with **project management** (issues, milestones, boards)

1. **Host** student & class websites (using [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/index.html)

1. Notice board & ask questions in the class [issues tracker](https://gitlab.fabcloud.org/academany/fabacademy/2025/class/-/issues)

---
class: middle, center

### Fab Academy GitLab structure

.logo_medium.center[
  ![Fabacademy Gitlab repo organization](images/gitlab-groups.png)
]

---
class: center

## Find your project

From the GitLab dashbaord, you should see your student documentation
website repository.

#### Example student URL:

gitlab.fabcloud.org/academany/fabacademy/2025/labs/**hosted-lab-name**/students/**my-name**

#### Example all students repository for a lab:

gitlab.fabcloud.org/academany/fabacademy/2025/labs/**hosted-lab-name**/students

#### Student list

**Current**: [fabacademy.org/2025/people.html](https://fabacademy.org/2025/people.html)

**Alumni**: [fabacademy.org/2025/prior.html](https://fabacademy.org/2025/prior.html)

---
class: middle, center

### Demo the GitLab interface

* Dashboard
* Fab Academy 2025 group 
* Student project
* Sidebar links
* List of project files
* How to edit a file
* Review CI (project builds)

Visit
[gitlab.fabcloud.org/academany/fabacademy/2025/](https://gitlab.fabcloud.org/academany/fabacademy/2025/)

---

**GitLab CI**

---
name: chapter-gitlab-ci

# GitLab CI

One of the killer features of Gitlab.

CI stands for [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) a common practice of software development.

---

## What this is capable of:

- Compiling websites with static site generators

- Make beautiful documentation using Gitbook, Sphinx, Mkdocs

- Automated Testing for software

- Resizing images

- Integrating content from different sources

- ...much more

Read more at [Gitlab Docs](https://docs.gitlab.com/ee/ci/)

---

## How does it work?

- You commit a `.gitlab-ci.yml` file in your repo (see [HTML example](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-html/-/blob/main/.gitlab-ci.yml))

- Push the commit

- Then a "runner" server will pick up your commit and start a "Pipeline" process for that commit

- Reading the `.gitlab-ci.yml` file will execute the above script in a [Docker](https://hub.docker.com/search?q=) container.

- After completing the steps in the `yml` file, GitLab stores the results (or publishes the file on the web for "pages" job)

.caption[
  Keep in mind, only the most recent Pipeline matters. So older pipelines from previous pushes/commits that failed can be ignore if the most recent commit passed successfully. 
]

GitLab has a list of example repositories for common static static site generators or HTML,
have a look at some of their `.gitlab-ci.yml` examples at: [gitlab.com/pages](https://gitlab.com/pages) or our [fabacademy templates](https://gitlab.fabcloud.org/academany/fabacademy/templates)

---

## CI build process flow

.full-width.center[
  ![](images/gitlab-ci-workflow.png)
]

---

#### Example CI: publish plain HTML files

```yml
# What type of docker container should run this job (ie. simple linux or python, php, etc)
image: busybox

# This is the "job" name (needs to be "pages")
pages:

# These are the commands that will be run in the job
  script:
    # (ie. for HTML nothing need done, so we just run a command saying nothing)
    - echo "nothing to do"
    
    # (ie. but for MkDOCS we need to build the HTML from markdown)
    - pip install -r requirements.txt
    - mkdocs build --site-dir public

# Tells GitLab which folder to keep after finish building
  artifacts:
    paths:
      # For GitLab Pages, we need a folder called "public" with html files
      - public
  
  # Defines when to run this "job" when a commit is pushed 
  rules:
    # (eg. only for the default branch)
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

---

## CI examples

In most of these examples, just delete all your old files and replace with new files

* [Example Mkdocs template](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-mkdocs) using Markdown (copy all the files if you want mkdocs)
* [Example Hugo template](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-hugo) (copy all the files to get started)
* [Example: Using NPM with framework example](https://gitlab.fabcloud.org/-/snippets/120) (React,Vue,Angular,etc)
* [Example: Using NodeJS to intall TailwindCSS with HTML](https://gitlab.fabcloud.org/-/snippets/117)
* [Current HTML student template](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-html) (if you want to go back to HTML only)

.caption[ What every you do in CI, the result needs to be a folder called "publish" to send to GitLab Pages ]

---

### Demo GitLab CI interface

Visit
[gitlab.fabcloud.org/academany/fabacademy/2025/site](https://gitlab.fabcloud.org/academany/fabacademy/2025/site/-/pipelines)

---

**Working locally**

---

## Setup Git locally

.caption[ If you do not want to use the WebIDE and commit every time to see your changes, you can work from your computer (plus no internet needed!)]

---

# What is Git

> [git-scm.com](https://git-scm.com)

- Git is a tool used for tracking to your project files
- Saving your changes is called a Commit
- Everything is stored in a Repository
- View history of all commits (who/when/what changed)
- Revert/restore past changes (good if anything breaks)
- Push commits (changes) to remote central repo (upstream/origin)
- Multiple locations can sync their changes with origin

[Learn Git by Baeldung](https://www.baeldung.com/git-guide)

[Wikipedia.org/wiki/Git](https://en.wikipedia.org/wiki/Git)

---

## Install Git on your computer

* _MacOS_: using Homebrew
  ```terminal
  brew install git
  ```

* _Ubuntu_: 
  ```terminal
  apt install git
  ```

* _Windows_: See [git-scm.com/downloads](https://www.git-scm.com/downloads) for examples

---

## SSH Keys

Git uses the SSH protocol to establish secure communication between your computer and the GIT server hosting your repository.
This makes sure only you can update your repository and nobody else can tamper the communication. We need to assign your user a special "key" only your computer has, no password needed!

#### Existing ssh key
You may _use your existing_ SSH key if you already have a _.ssh/_ folder

#### Generate a new SSH Key ([see docs](https://docs.gitlab.com/ee/user/ssh.html#generate-an-ssh-key-pair))

- Linux and MacOS

```terminal
  ssh-keygen -t ed25519 -C "ssh-for-gitlab-fabcloud"
  ```

- Windows
  [Using PuttyGEN](https://the.earth.li/~sgtatham/putty/0.67/htmldoc/Chapter8.html#pubkey-puttygen)

---

### Add the public key to your GitLab profile

[See GitLab docs](https://docs.gitlab.com/ee/user/ssh.html#add-an-ssh-key-to-your-gitlab-account)

Copy the **PUBLIC KEY** only (`.pub`), from where you just created the keys:

```terminal
  cat ~/.ssh/id_ed25519_fabcloud.pub
```

---

## Clone your project locally

Verify you can connect to Gitlab (you see "Welcome to GitLab") 
```terminal
ssh -T git@gitlab.fabcloud.org
```

* Go to your students project page (in GitLab)
* Click the blue "clone" to copy the **SSH URL**.
* Then in your terminal, use command `git clone` followed by the copied URL.

```terminal
git clone git@gitlab.fabcloud.org:fabacademy/student-demo.git my-fabacademy-doc
```

Having connection issues:
* [use specific ssh key](https://docs.gitlab.com/ee/user/ssh.html#use-different-keys-for-different-repositories)
* [Use SSH on Microsoft Windows ](https://docs.gitlab.com/ee/user/ssh.html#use-ssh-on-microsoft-windows)
* See [GitLab docs](https://docs.gitlab.com/ee/user/ssh.html)
---

## Tell GIT who you are

It is a good idea to configure git on your computer with your name and email,
so that when you make commits they can be attributed to you.

```terminal
git config user.name "Your Name"
git config user.email "your.email@example.com"
```

.caption[
	Please use the **same name and email** address as your fablabs.io/Gitlab account (check your GitLab settings).
]

See commit author below, from `git log`:
.logo_medium.center[
	![](images/git-commit-log.png)
]

---

## About Git staging process

The diagram below illustrates the different areas in your local git repository.
.full-width[
  ![](images/git-staging.png)
]

---
name: chapter-git-push

## How to push local changes

After making some changes to files, you will want to push these changes to GitLab so they can get published.

First have a look at the state of your working directory and staging area.
```terminal
git status
```
Next selected the changed files, moving them to the staging area.
```terminal
git add docs/path-to-your-file.md
```
Commit the selected changes in the staging area, including a message.
```terminal
git commit -m "Added my name"
```
Push your new commit to remote repository, GitLab.fabcloud.org.
```terminal
git push
```

---

## Try your first commit!!

For example, if you have not already done so, sign your "Student Agreement" to your repository.

* [Copy of agreement](https://fabacademy.org/2025/doc/students.md) to a file in your folder.

* Edit the agreement and **add** your full name.

* Commit the new file as described in previous slide.

---

## Check errors when pushing

Example what an error looks like when pushing in GIT.
.full-width[
  ![](images/git-push-error-size.png)
]
.caption[
   This error is GitLab limiting you to 10MB per commit. Amend your previous commit to remove some larger images/files.
]

---

## How to pull latest changes

It is a good idea to always check if there are commits on the remote repository you do not have locally.
This can happen if you made changes directly on GitLab or someone else pushed some commits.
```terminal
git pull --rebase
```
.caption[
	Make sure you have no pending changes in your working directory before pulling.
	It is safe to run this command all the time, as there is no destructive behavior by default
]

To reset your local repo to match what is in GitLab (removing any local changes and pending commits). This is good way if things are just not working and you are stuck.

```terminal
git reset --hard origin/main
```

---

## Extra useful commands

To see what has changed in the file contents of your working directory.
```terminal
git diff
```
.caption[
	The markings `---` means line was removed, while `+++` means adding a line.
]

See a log of all recent commits
```terminal
git log --graph
```
.caption[
	You can also see visual graph history of commits in GitLab or with a GUI application
]

---

layout:true

---
# Additional links
- [Learn Git by Atlassian](https://www.atlassian.com/git/tutorials/what-is-version-control) (nice descriptions and diagrams)
- [Learn Git by GitTower](https://www.git-tower.com/learn/)
- [Dangit, Git!](https://dangitgit.com/) (common git problems)

- [Fab Academy 2019 Tutorials Git cheat ](https://fabacademy.org/2019/docs/FabAcademy-Tutorials/week01_principles_practices_project_management/git_simple.html)
- [Fiore's recitation from 2019](http://fabacademy.org/2019/recitations/version-control/)
- [Recitation 2020 by Kris and Viktor.](http://academany.fabcloud.io/fabacademy/2020/recitations/version-control/)

---

## File sizes in your website

* You should optimize your images and videos for viewing on website

* Keep in mind, each time someone views your website, they download your images

* _Good defaults (soft limits)_: 
  * Target images to be maximum 800px wide (less than 100KB)
  * videos: try to optimize each video getting like 1-5MB (MAX max 10MB)
  * you do not need 4k or 1080p to show a blinking light ;)
  * Avoid GIFs (except for memes :)

* Why? 
  * Hard limit of 500MB per website (deployed!)
  * calc: 100 images of 100KB per week (_multiply by_) ~19 weeks = **185 MB**
  * Plus probably adding some optimized videos per week (max 10MB) = **~200MB**
  * Then in theory you have ~100MB as extra space in case you want a few high quality images/videos through the year for some special highlights that your proud of!
  ** **PLAN** a budget of how much space you can use each week (track it!)

---
layout: true

**Example: Use markdown & Mkdocs for website**

---
name: chapter-setup-mkdocs

## Manually working with HTML files

Working with HTML files, shared parts like the navigation bar would need to be copied to each file manually. See the two files below, the navbar need to be same.

---

## Using Markdown for HTML

* A markup language which allows easy to read and write plain-text document
* Tools, like mkdocs, exist to convert markdown to valid HTML in a predictable manner

---

## About MkDocs

* Tool, called a static site generator, made for project documentation
* Documentation is mainly written in Markdown
* Install themes to have a different style of websites
* Then can be customised with theme options
* Builds your HTML site from the markdown and theme
* Can also add extra plugins & extensions to add features to your site

See more at [mkdocs.org](https://www.mkdocs.org/)

---

### Basic files for a Mkdoc project

* **mkdocs.yml** (configuration file for website)
* **requirements.txt** (use to install mkdocs, themes, plugins)
* **docs/** (folder for all markdown files and images)
    * eg. _docs/index.md_
    * eg. _docs/assignments/week03.md_
    * eg. _docs/images/profile.png_
* **.gitlab-ci.yml** (CI file to build mkdocs website and publish HTML)

### Interested?
* check out the template: [academany/fabacademy/templates/student-template-mkdocs](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-mkdocs/)
* Use your project WebIDE, or locally, to copy all the files listed above
* Read how to add pages [on mkdocs website](https://www.mkdocs.org/getting-started/#adding-pages)
* check out installed [material theme](https://squidfunk.github.io/mkdocs-material/setup/)

<br>
#### Time for a Demo?

---

## Typical CI errors

### CI does not know where to get the theme

```terminal
$ mkdocs build --site-dir public
ERROR    -  Config value: 'theme'. Error: Unrecognised theme name: 'sunshine'. The available installed themes are: material, mkdocs, readthedocs
Aborted with 1 Configuration Errors!
```

> Remember, add the theme to the `requirements.txt` file with a version number

---

## Typical CI errors

### Possible mistake in _mkdocs.yml_ file or indentation:

```terminal
$ mkdocs build --site-dir public
Error: MkDocs encountered an error parsing the configuration file: mapping values are not allowed here
  in "/builds/academany/fabacademy/2025/example/site/mkdocs.yml", line 26, column 10
```

> Check the last commit, and revert the change, or review the mkdocs.yml vs the mkdocs/theme docs. Also check the file is valid yml (ie. [yamllint.com](https://www.yamllint.com/))

---

**Example: Using Hugo framework for website**

---

## Next level: [Hugo framework](https://gohugo.io/)

If you'd like a bit more advance framework vs mkdocs, one option is Hugo:

* Easy to install, with a simple binary file to run
* Can use markdown for all pages
* For customizable than mkdocs
* Easy custom theme or pre-built at https://themes.gohugo.io/

<br >

See [getting started docs](https://gohugo.io/getting-started/) for more info on Hugo:

Example template at [academany/fabacademy/templates/student-template-hugo](https://gitlab.fabcloud.org/academany/fabacademy/templates/student-template-hugo)