On Fabcloud our individual repositories are housed under Academany > FabAcademy > Year > List of Labs > Lab > Students > Name. One way to log on to Fabcloud is use login credentials from fablabs.io. That is also what you use for other FabAcademy communication.
1. Install Git on your local computer.
Install Git through the command line - Terminal app (macOS).
Install [Homebrew](https://brew.sh/), a package manager using the instructions on the website.
and then
`brew install git`
On Fabcloud our individual repositories are housed under *Academany > FabAcademy > Year > List of Labs > Lab > Students > Name*
One way to log on to Fabcloud is use login credentials from fablabs.io. That is also what you use for other FabAcademy communication.
1. Install Git on your local computer.
Install Git through the command line - Terminal app (macOS).
Install [Homebrew](https://brew.sh/), a package manager using the instructions on the website.
and then
`brew install git`
There are other ways to install git as mentioned on the website too.
Ref:https://git-scm.com/download/mac
2. Configure user
To configure your user from scratch, in your terminal, add your Git username and set your email fro uploading
This helps in tracking who makes the changes on the shared gitlab repo which is public.
3. Generate SSH key
Check if you have an SSH KEY already
`cat ~/.ssh/id_rsa.pub`
If not, generate it using
`ssh-keygen -t rsa -C "emaitee@gmail.com"`
Then use the above command to view your public key and copy it.
Upload this key on the Gitlab Website onthe browser. Go to user profile > Settings > SSH keys and copy it there.
Now, your Gitlab server is securely linked to your local computer.
4. Start a git repository
On your local computer, make a new folder wherever you want to store your documentation.
Using terminal, cd to that folder and make it a git repo Using
`git init`
This initialises the local folder as a git repo.
5. Clone repository
Your student repo consists of the default student template. First task is to clone this existing template to your local repo. After you cd to your local repo, use this to clone.
This helps in tracking who makes the changes on the shared gitlab repo which is public.
3. Generate SSH key
Check if you have an SSH KEY already
`cat ~/.ssh/id_rsa.pub`
If not, generate it using
`ssh-keygen -t rsa -C "emaitee@gmail.com"`
Then use the above command to view your public key and copy it.
Upload this key on the Gitlab Website onthe browser. Go to user profile > Settings > SSH keys and copy it there.
Now, your Gitlab server is securely linked to your local computer.
4. Start a git repository
There are several ways to make a repository:
1. On the GitLab website, create a repository and then clone it locally.
2. In the terminal initialising it from scratch using `git init` by changing current directory to desired location.
3. Cloning an existing one.
Since out student repos on GitLab already have a default template installed, we can directly clone it on our local computer, wherever you want to store your documentation.
Your student repo consists of the default student template. First task is to clone this existing template to your local repo. After you cd to your local repo, use this to clone.
Now, you have made a clone of the template on your local repository.
4. Basic workflow and repository structure
---
The most routine workflow for git : **status-(pull)-add-commit-push**
`git status` to check what's happening with the current directory, check if the local and remote repos are synced or need to be updated
`git pull` to pull files from the remote repo to the local repo, very important if multiple people are pushing to the repo
The most routine workflow for git : **status-(pull)-add-commit-push**
`git status` to check what's happening with the current directory, check if the local and remote repos are synced or need to be updated
`git pull` to pull files from the remote repo to the local repo, very important if multiple people are pushing to the repo
`git add .` to add all changes from the working directory to the staging area
`git commit -m "action msg"` to commit changes from the staging area to the local .git repo, adding a message helps identify and keep a track of the changes made in that particular commit
`git push` to push only the changes from the local .git repo to Gitlab cloud repo
`git commit -m "action msg"` to commit changes from the staging area to the local .git repo, adding a message helps identify and keep a track of the changes made in that particular commit
`git push` to push only the changes from the local .git repo to Gitlab cloud repo
I find this diagram very helpful to visualise the directory structure:
My first commit from git log
My first commit from git log
Some other commands that might help:
`git clone` Clone a repository into a new current local directory, to do once at the beginning of documentation
`git init` Create an empty Git repository or re-initialize an existing one (starts a .git folder on local computer where all changes will be saved)
`git help` for help with git commands
Git had very detailed error msgs, so it is advisable to read and follow them to find solutions with issues.
`git diff` Show changes between commits, commit and working tree, etc
`git log` Show commit logs
Some other commands that might help:
`git clone` Clone a repository into a new current local directory, to do once at the beginning of documentation
`git init` Create an empty Git repository or re-initialize an existing one (starts a .git folder on local computer where all changes will be saved)
`git help` for help with git commands
Git had very detailed error msgs, so it is advisable to read and follow them to find solutions with issues.
`git diff` Show changes between commits, commit and working tree, etc
`git log` Show commit logs
It is easier to undo a staged file, i.e. after git add
but more difficult to undo a committed file, after git commit, but still possible.
Check this guide in case of need to undo anything.
Ref: [How to undo (almost) anything with Git](https://github.blog/2015-06-08-how-to-undo-almost-anything-with-git/)
It is easier to undo a staged file, i.e. after git add
but more difficult to undo a committed file, after git commit, but still possible.
Check this guide in case of need to undo anything.
Ref: [How to undo (almost) anything with Git](https://github.blog/2015-06-08-how-to-undo-almost-anything-with-git/)
5. About CI/CD
---
Continuous Integration complies websites with static site generators.
Here is a guide to understand how and why *commit > build > test > stage > deploy* works so effciently.
Ref:[CI/CD Explained in 100 Seconds](https://www.youtube.com/watch?v=scEDHsr3APg)
How it works...
You create a gitlab-ci.yml file (HTML).
Then a "runner" server picks up your "Pipeline"
Reading your .gitlab-ci.yml file will execute your scripts in Docker.
After completing your steps in the .yml file, GitLab stores the results and publishes them on the web.
6. YAML file
---
I recently learned how to make a website using HTML, CSS with a Bootstrap framework. To develop my webpage, I wanted to explore different Static Site Generators before fixing on one. So I started by setting up both Mkdocs and Jekyll. Hugo was another option I want to look into in the coming weeks.
Static Site generators
7. YAML file
First git reads the YAML file .gitlab-ci.yml in the repo.
GitLab has a list of example repositories for common static static site generators or HTML at [gitlab.com/pages]
(https://gitlab.com/pages).
Understanding the default Mkdocs-CI YAML file in the repo
```
# What type of container should run this job (where the script will run)
image: python:3.8-slim
# This is the "job" name
pages:
# This tells GitLab which group the "job" belongs
stage: deploy
# Set any environment variables to be available inside the container
variables:
GIT_DEPTH: 1000
# These are the commands that will run in the job
script:
# This is a specific mkDocs command to make the HTML
- time mkdocs build --site-dir public
# Tells GitLab which folder to copy out of the "job" to send to another "job"
artifacts:
paths:
# Select the public folder in this case, so it can be sent to GitLab Pages
- public
only:
- master
```
7. Web Development with SSGs
---
First git reads the YAML file .gitlab-ci.yml
https://gitlab.com/pages This page has examples of different .yml files which changes according to Static Site Generaotrs
like Hugo, Jekyll, or Wikis like Gitbook, etc. and even plain-HTML. The FabAcademy default website is based on Mkdocs.
The basic way to make a website is using HTML code for content, and maybe using CSS and javascript for styling.
Another efficient way to make websites is to use static site generators, especially sites with...
To develop my webpage, I use the existing Mkdocs to first understand how it works. Jekyll is another option I want to use to make a custom themes maybe later on.
There are many options of Static Site generators like Hugo, Jekyll, Gitbook, Mkdocs, Middleman, etc. each with their own special features for the kind of website one wants to make.
This GitLab page has a list of example repositories for common static static site generators or HTML at [gitlab.com/pages]
(https://gitlab.com/pages).
8. Web Design
---
Grid, colours, font - Helvetica, if you write a sentence in helvetica it is supposed to be the truth. (-Barbara Stauffacher Solomon)
### Setting up jekyll
---
I followed this [Jekyll tutorial](https://jekyll.org) by [Giraffe Academy](https://www.youtube.com/playlist?list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB). Before installing jekyll, I checked if I had these supporting things, and updated them:
1\.**Homebrew:** to easily install software packages
2\.**Ruby:** programming language that jekyll is written in
3\.**RubyGems:** package manager for ruby
4\.**Bundler:** to track and install gems and versions in a group, for jekyll themes
Homebrew, Ruby and Gem were all pre-installed.
So I checked versions using
`ruby -v` and `gem -v`
I installed bundler with `gem install jekyll bundler`, but got a permissions error msg.
So, I tried it with sudo like so: `sudo gem install jekyll bundler` and it worked.
And then to make sure checked version: `gem install jekyll bundler`
To view the changes on my local server `http://localhost:4000` I used `bundle exec jekyll serve` the first time and `jekyll serve` everytime after.
I wanted my website to be as simple as possible from features, animations, colours, etc. So that the content is not overpowered by any distractions. I used the [MKdocs material theme document guide](https://squidfunk.github.io/mkdocs-material/getting-started/) to change colours, fonts, etc.
///Grid, colours, font - Helvetica, if you write a sentence in helvetica it is supposed to be the truth. (-Barbara Stauffacher Solomon)
//# Setting up jekyll
//---
//I followed this [Jekyll tutorial](https://jekyll.org) by [Giraffe Academy](https://www.youtube.com///playlist?list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB). Before installing jekyll, I checked if I had these supporting things,
//d updated them:
//1\.**Homebrew:** to easily install software packages
//2\.**Ruby:** programming language that jekyll is written in
//3\.**RubyGems:** package manager for ruby
//4\.**Bundler:** to track and install gems and versions in a group, for jekyll themes
//Homebrew, Ruby and Gem were all pre-installed.
//So I checked versions using
//`ruby -v` and `gem -v`
//I installed bundler with `gem install jekyll bundler`, but got a permissions error msg.
//So, I tried it with sudo like so: `sudo gem install jekyll bundler` and it worked.
//And then to make sure checked version: `gem install jekyll bundler`
//To view the changes on my local server `http://localhost:4000` I used `bundle exec jekyll serve` the first time and
//Jekyll serve` everytime after.
### Setting up Mkdocs
Setting up Mkdocs was a similar process. Intalling and upgrading package manager pip `pip install --upgrade pip` to install mkdocs: `pip install mkdocs`
Intalling and upgrading package manager pip `pip install --upgrade pip` to install mkdocs: `pip install mkdocs`
To view the changes on my local server `http://127.0.0.1:8000` I used `mkdocs serve`
#### Themes
I tried to clone and modify some jekyll themes I downloaded from [rubygems.org](https://rubygems.org/). While pushing it to gitlab, I wasn't sure what files to keep from the default fabcloud repo. So I replaced them all, but there was an issue with my pipeline. I think it has something to do with the config.yml file. While I figure that out, I'm using this default template to document my process.
### Useful links
*[Jekyll](http://jekyll.org)[tutorial by Giraffe Academy](https://www.youtube.com/playlist?list=PLLAZ4kZ9dFpOPV5C5Ay0pHaa0RJFhcmcB)
