Week 1. A. Project Management

Introduction 🖊

The first Fab-Week starts challenging for me! 🚀 We’ll create our own website, learning the basics of using a terminal, GIT, HTML, CSS, Mkdocs & Markdown. Things that I never did before. 🤗

Flashback: During the past week we had a boot camp session, where we introduced ourselves, talked about our early final project ideas, carryed on a really cool soldering workshop organized by Erwin - thanks for that 🤙 - we download the softwares which we’ll need for the fab-course, and had a short introduction about Visual Studio Code by our fellow Bente. What a Start!

Fab Assignments 📚

  1. Made a website and described how you I did it
  2. Created a section about myself on my website ✔️
  3. Documented steps for creating my Git repository & Adding files to it
  4. Push my website to the class GitLab
  5. Signed and uploaded Student Agreement ✔️

My Goals 🎯

Process 🏊‍♀️

Opening for the first time the Terminal of my MacBook

As I previously introduced, I never used a terminal before. I have to admit that I never felt very attracted to the “programming world” so thinking about learning about HTML, using a terminar & GIT sounded like a big challenge to me.

Researching about terminals

When Henk introduced us the terminal’s concept, I wanted to go more in deep and undestarnd Why we should use it instead of the ordinary commands. I did researched about it, and everything I founded sayd something like: You Gain Greater Control over System Functions. So I guessed I will discover its real power while using it during the Fab-Course.

Learning the basic terminal commands

The first thing I did when I openned the terminal, was creating a folder for the Fab Academy using the basic commands:

So I named my folder like: “fabacademy” - without capital letters and spaces, to make it easier to read by the terminal. Here is where I will save all the data & softwares that I need during for the Fab academy course, in order to work neatly.

My fellow students showed me how to open the terminal pointing direcly to one of my folders. I found this command very handy to use with the “fabacademy” folder that I just created, in this way you can skip a few steps when working with it. What you need to do is to right-point on the folder, and then press on “New Terminal Tap at Folder”.

Installing HomeBrew & Git

Next task was installing HomeBrew in my laptop. This package is very reccomendated for macOs in order to download programs which are not available in the Apple Store.

In fact, if you want to download Git from your terminal you will need to have pre-installed HomeBrew! The command you’ll need to use is this one:

$ brew install git

After installing Git, you’ll need to configure your username and mail by using this commands:

$ git config --global user.name "Your Name"
$ git config --global user.email "name@yourdomain.com"

Setting up a Connection to Gitlab

This is my Repository at GitLab. Each student has a pre-setted website - developed with MKDocs and Material for Docs - where has to upload their Weekly assignments.

Set up SSH for Gitlab

Why?

When setting up a connection to GitLab, it is recomended to use a SSH Key instead of HTTPS. This is because SHH keys are a much better choice for securely authenticating the GitLab account.

In fact, things tend to get a little more complicated when sending Git commands to a server over HTTPS demands. The user submit their username and password in order to perform each action. This can result in quite a lot of prompts.

What?

In order to communicate over SSH (Secure Shell), We need to have an SSH key pair. Each SSH key pair has a public and a private key:

When using an SSH key pair as a method of authentication, the public key is stored on the server. It doesn’t really matter if it can be viewed as it is public information. The private key, however, is kept by the user and should not be copied or exposed in any way.

Once this is set up, the server can ask the user for proof of identity using the public key and the user can prove it using the private key.

SSH in Gitlab

SSH keys are one of the choices for authentication against GitLab servers. This is because the majority of actions we will be taking on GitLab via SSH will be pushing changes from our local git repository to the hosted repository on GitLab.

In order to set up the SHH in Gitlab, I followed the instructions from the official page.

Firstly I setted up two different SSH key pairs. I used ED25519. This creates a public and secret key file within the ./ssh folder

$ ssh-keygen -t ed25519 -C "my-email@email.com" -f ~/.ssh/id_ed25519_github

$ ssh-keygen -t ed25519 -C "my-email@email.com" -f ~/.ssh/id_ed25519_gitlab

Because I don’t want to type in my SSH key passphrase every time I make use of it, I added both keys to my ssh-agent by running.

$ ssh-add ~/.ssh/id_ed25519_github

$ ssh-add ~/.ssh/id_ed25519_gitlab

In the ssh folder I created a config file:

$ touch ~/.ssh/config

Save these settings in the ~/.ssh/config in the file:

Host *
  AddKeysToAgent yes
  UseKeychain yes   

# Personal GitHub account
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github

# Personal GitLab account
Host gitlab.com
  HostName gitlab.com
  Preferredauthentications publickey
  IdentityFile ~/.ssh/id_ed25519_gitlab

Add the public keys to GitLab (and GitHub). I copied the GitLab public key with:

$ pbcopy < ~/.ssh/id_ed25519_gitlab.pub

Finally, I went to the GitLab page. In Settings > SSHH Keys I pasted the key, name my pc and saved it.

Clone my website repository on my MacBook

In order to be able to make changes on that website using my local terminal, I need to clone the website repertory on my laptop. This was easy to do, I just needed to clone or the HTTP or the SSH links, which can be found at the landpage of my repository using this command on the terminal:

$ git clone https://gitlab.fabcloud.org/academany/fabacademy/2022/labs/waag/students/paola-zanchetta.git

In my case, I used the HTTPS.

Visual Studio Code

Thanks to our fellow student Bente, We had an introduction to “Visual Studio Code”, the text editor which I will use during the Fab Academy course to make the assignmenets documentation.

Creating my Website

In order to learn How to modify the pre-setted student’s website, I firstly followed the tutorials from Fab Academy to work with MkDocs and Material for Docs. In this way, i created in a local server a mock website with the basic skeleton that I would need to follow the course.

As soon as I saw that I understood the concepts and the commands began to come out with MkDocs. I set out to learn how to use other static generator platforms like:

I decided to use Hugo. In order to use it, I needed to downloaded it first, suing the bew command:

$ brew install hugo

Commiting and Pushing with VisualCode

When editing the code with VisualCode, it is very easy to commit and push changes to the repository.

For commiting, follow this steps:

The changes will be now commited. If you want to push it to the respository, you will need to follow this steps:

Choosing a Theme

I researched about the best option for my Hugo theme, and finally I came up with the Showroom one. Since my ideas was to go one step further and learn about How to edit and personalize it I choosed one where this changes could be duable to do by someone with low experience with HTML.

In order to make it work, I followed the outiline from the Hugo website.

Adding and Modifying content

List of what I added:

Add Images

I was not able to add a Portrait photo, then I realized was because I was using the wrong path. A trick is to always put all the photos in the same static folder on the roof folder.

In order to add photos, I use the following path when working from the blog content:

![name-pic-N](../../weekN/weekN-m.jpg)

When adding pics in the about page or final project, I need to use the following path:

![name-pic-N](../weekN/weekN-m.jpg)

Add new Pages in the Header

I played around with the Theme’s “partials” to make a website personalized to my needs.

I did added 2 extra pages in the header:

In order to do so, I modified the following code found following this path:

LAYOUTS > PARTIALS > HEADER

<header class="w-full px-4 pt-4 max-w-5xl mx-auto">
  <nav class="flex items-center justify-between flex-wrap">
    <div class="flex gap-2 items-center">
      {{ with .Site.Params.authorEmail}}
      <a href="mailto:{{.}}" aria-label="EMail">
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="20"
          height="20"
          viewBox="0 0 24 24"
          stroke-width="1.5"
          stroke="currentColor"
          fill="none"
          stroke-linecap="round"
          stroke-linejoin="round"
        >
          <path stroke="none" d="M0 0h24v24H0z" fill="none" />
          <circle cx="12" cy="12" r="4" />
          <path d="M16 12v1.5a2.5 2.5 0 0 0 5 0v-1.5a9 9 0 1 0 -5.5 8.28" />
        </svg>
      </a>
      {{end}}
      <a href="{{ .Site.Home.Permalink }}" class="flex items-center font-bold">
        {{ .Site.Title }}
      </a>
    </div>

    <ul id="nav-menu" class="flex w-auto mt-0 space-x-2">
      {{ with .Site.GetPage "/about" }}
      <li>
        <a href="{{ .Permalink }}" class="hover:text-blue-800 dark:hover:text-blue-300">{{ .Title }}</a>
      </li>
      {{ end }}
      {{ with .Site.GetPage "/blog" }}
      <li>
        <a href="{{ .Permalink }}" class="hover:text-green-800 dark:hover:text-blue-300">{{ .Title }}</a>
      </li>
      {{ end }}
      {{ with .Site.GetPage "/page" }}
      <li>
        <a href="{{ .Permalink }}" class="hover:text-pink-800 dark:hover:text-blue-300">{{ .Title }}</a>
      </li>
      {{ end }}
      {{ with .Site.GetPage "/blog2" }}
      <li>
        <a href="{{ .Permalink }}" class="hover:text-yellow-800 dark:hover:text-blue-300">{{ .Title }}</a>
      </li>
      {{ end }}
    </ul>
  </nav>
</header>

I also changed the colors of the names of the header in the same code to blue, green, pink and yellow.

Pushing it into GitLab

I followed the steps in this website to move my Hugo files to my Fab Academy GitLab repository.

I had some problems with this step, but I finally solved it using the following code:

image: registry.gitlab.com/pages/hugo/hugo_extended:latest

stages: 
- install 
- deploy

install_packages:
  stage: install
  script:
  - apk add --update npm
  - npm install -g postcss-cli
  - npm install 

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages: 
  stage: deploy
  script:
  - apk add --update npm
  - npm install -g postcss-cli
  - npm install
  - hugo -D -F
  artifacts:
    paths:
    - public
  only:
  - master