01 | Principles and Practices + Project Management

Lecture

Review

Weekly assignments checklist

Principles and Practices

1. Communicate an initial project proposal

Have you?

• Sketched your final project idea/s
• Described briefly what it will do and who will use it

Project Management

1. Build a personal site describing you and your final project.
2. Upload it to the class archive.
3. Work through a git tutorial.

Have you?

• Made a website and described how you did it
• Created a section about yourself on that website
• Added a page with a sketch and description of your final project idea(s)
• Documented steps for creating your Git repository and adding files to it
• Pushed to the class GitLab
• Signed and uploaded Student Agreement

As I started to write this page for the first week, I quickly noticed that the text was getting really long as seems to happen with many Fab Academy documentation sites. Therefore, I have decided to break off some of the things I write into a separate section of the site called Tutorials. I will add there things and topics that are not exactly at the core of the weekly assignments, but still somehow relevant and useful to document.

For this week I made the following additional tutorials:

• How to setup a fresh MacOS computer for Fab Academy.

How I built my website

The following is a documentation of my process on setting up git to work with the student website repository and also the first steps in creating this website.

Working with git

Git was already familiar to me, but there are always things I forget how to do and there are definitely many things that I don’t yet understand or know about. As a refresher to the topic, I went through this tutorial (and of course googled around if I messed up something as I was working). Nadieh’s site was also an excellent guide.

SSH

Before I can actually do anything, I need to configure an SSH key to securely connect to the repository.

I already have SSH keys on my computer that I use with GitHub and GitLab. I have separate keys for both. From a little bit of research that I did, there seemed to be a lot of conflicting information on using the same SSH key for different services. I made a new one anyway for fabcloud just so I can document the process here.

ssh-keygen -t ed25519 -C "my-email@example.com" -f ~/.ssh/id_ed25519_fabcloud

This creates two files to your ~/.ssh folder:

.
├── id_ed25519_fabcloud
└── id_ed25519_fabcloud.pub

Then I added the key to my Keychain so I don’t have to type in the password all the time:

ssh-add ~/.ssh/id_ed25519_fabcloud

You can then configure what key you use for specific services by adding some setting to your git config file.

nano ~/.ssh/config

Nano is a text editor that works in the Terminal and is installed by default on macOS. I like it more than vim. Here are the contents of my file:

Host *
   AddKeysToAgent yes
   UseKeychain yes

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

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

# Fab Academy account
Host gitlab.fabcloud.org
   HostName gitlab.fabcloud.org
   Preferredauthentications publickey
   IdentityFile ~/.ssh/id_ed25519_fabcloud

Then I copied the public key for adding to GitLab. This command copies the contents of the file to your clipboard:

pbcopy < ~/.ssh/id_ed25519_fabcloud.pub

• Go to your repository settings over at GitLab: User Settings -> SSH Keys
• Paste the contents of your clipboard to the Key field
• Give your key a Title
• You can also add an Expires at date if you wish
• Click Add key

Now you should be all set to start working on your site. You can test that everything is fine with:

ssh -T git@gitlab.fabcloud.org

I got this as a reply, so everything should be good:

Welcome to GitLab, @matti.niinimaki!

Cloning my repository and configuring git

Phew, now I can finally start working on the actual files of the website.

The first thing I did was to navigate to a folder on my computer where I want to keep my site files:

cd Sites

Then I cloned my repository to that folder:

git clone git@gitlab.fabcloud.org:academany/fabacademy/2022/labs/aalto/students/matti-niinimaki.git

and navigated to that newly created folder:

cd matti-niinimaki

I am signed up to Fab Academy with my Aalto University work email, but generally I use git with an email from my own company. Therefore, I configured my Fab Academy site to use local email and user name that are different from the ones I normally use. So make sure you are in your repository folder and do:

git config user.name "Matti Niinimäki"
git config user.email myemail@idontwanttowriteithere.fi

If you are reading this in order to get some help to setup your own repository, you probably want to configure these settings globally using:

git config --global user.name "Your Name"
git config --global user.email you@example.com

I also use the following settings for git:

git config --global core.editor nano
git config --global init.defaultBranch main

To check your git configuration settings globally:

git config --list

To check your git configuration settings locally:

git config --list --local

Press q to exit the view that pops up.

Basic git commands

At this point I could edit the files on my computer and even see the changes on a local server. This is how to do it.

Use cd to navigate to the folder:

cd ~/Sites/matti-niinimaki

Open the folder with Visual Studio Code

code .

I made a tiny change to the default site that was provided to us just to make sure everything works.

Back in Terminal, I first check the git status.

git status

This told me that I had some Changes not staged for commit. So I added the files to the staging area:

git add .

The . adds all of the files in the current project. Just be careful with this, I have seen quite many people accidentally make their entire hard drive or user folder as a git repository. You can use git status again to see that this worked.

I moved on to the next step which is to commit these changes.

git commit -m "message that describes what you have changed"

Then the last step is to push the changes.

git push

Now you can go back to your repository page to see if the commit appears in the remote repository. Everything seemed to work fine so I was satisfied that everything works.

This MkDocs setup seemed to be quite nice after I did some initial testing, but I wanted to explore some other options also, so I deleted all of the files in my local repository and started from scratch.

Hugo

I wanted to use a static website generator that uses Markdown because it’s just so much nicer to work that way compared to anything else I have tried over the years. Writing human readable text in a code editor with all my files right there on a local hard drive and not having to keep track of HTML tags allows me to focus on the actual content. However, I can still use plain HTML when needed. Love it.

Out of all of the static website generators I tested (Jekyll, MkDocs, Hugo), I chose Hugo for my Fab Academy website for the following reasons:

• It seemed to have a lot of flexibility, doesn’t have dependencies, easy installation process.
• Speed: Builds really fast! Jekyll being clearly the slowest, MkDocs was also pretty good but Hugo took the win.
• Themes: There seemed to be quite nice themes that I could use as a starting point. Jekyll was a clear winner in this category but I just need something basic that I can modify if needed. MkDocs seemed to only have technical documentation themes which would have been fine since I’m going with that in any case, but I wanted to explore Hugo also for some other sites I’m currently working on.
• Kris always goes on about how nice it is. So I wanted to see what all the hype was.

I had started to work with Hugo about a month or two ago, since I wanted to rebuild my own website and also make a couple of new ones. I also knew that I was going have to do this for Fab Academy so I took a little bit of a headstart.

Setting up Hugo

Installing Hugo on macOS is quite easy if you have Homebrew installed. Just do:

brew install hugo

Navigate to the parent folder where my repository folder is:

cd ~/Sites

Make a new site. I have to use --force because the folder already exists.

hugo new site matti-niinimaki --force

Themes for Hugo

Firstly, I was going to just go with an existing theme. I had picked the Book theme, because of it’s minimalism and good documentation. It also didn’t seem to be bloated with features I would never use. I made a tutorial video for my students at Aalto University and I will upload it later to the tutorials section of the page.

The image below is my first version of the site I made with the Book theme.

However, as I learned more and more how Hugo works, I really wanted to customize almost everything. It quickly became clear that I should maybe just make my own theme. I initially created the theme you see for my website, but I am continuing the development of the theme for a more general purpose. Once it feels complete enough, I will break it off into it’s own git repository. For now you can see my theme evolving inside the themes/mnstri-hugo-fab-theme folder of my repository. I used the Book theme as a way to learn how to do it and implemented some features from that theme to my own.

Continuous deployment using GitLab and Hugo

Hugo has a guide on how to deploy a site using GitLab. There is also a template made for Hugo + GitLab. I created my file based on them, but there are some things that might not work for you. Or at least I ran into a couple of problems.

The theme I created uses Bootstrap. I wanted to be able to use SCSS to easily overwrite the default Bootstrap styling and variables. Hugo has a built-in functionality to convert .scss files into one .css file, but this requires the extended version of Hugo. Therefore, I had to use the following to make sure GitLab also uses the extended version of Hugo.

# All available Hugo versions are listed here:
# https://gitlab.com/pages/hugo/container_registry
image: registry.gitlab.com/pages/hugo/hugo_extended:latest

I had an issue earlier with GitLab on another site I was working with. It gave an error that said:

Failed to read Git log: Git executable not found in $PATH

I didn’t actually test if this is also an issue with our fabcloud GitLab, but just to avoid it happening again, I added the following to my .gitlab-ci.yml file:

before_script:
  - apk add --update --no-cache git

Another issue that we discovered at Aalto Fab Lab was that Safari browser on iOS did not play video files on the GitLab published sites. I found a fix here.

pages:
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"

This is the full CI/CD file. Seemed to work fine so I will not poke it anymore unless some problems appear.

# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/ee/development/cicd/templates.html
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Pages/Hugo.gitlab-ci.yml

---
# All available Hugo versions are listed here:
# https://gitlab.com/pages/hugo/container_registry
image: registry.gitlab.com/pages/hugo/hugo_extended:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

test:
  script:
    - hugo
  except:
    variables:
      - $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

pages:
  variables:
    FF_USE_FASTZIP: "true"
    ARTIFACT_COMPRESSION_LEVEL: "fastest"
  script:
    - hugo
  artifacts:
    paths:
      - public
  only:
    variables:
      - $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

before_script:
  - apk add --update --no-cache git

Note that my script says just hugo. When I test the site locally, I use hugo serve -D -F which also publishes the draft versions and pages where the date has been set to the future. I just need to make sure I remember to change the draft parameter on my pages front matter whenever I want to publish the page. Click here to find all the build options.

Things that did not work

I wanted to change the default branch of my repository from master to main. It seems that I don’t have the required rights for the repo to do this. But here is the process, in case I need to do it somewhere else.

Rename local repository and push it to the remote:

Open your repository settings in GitLab and make the main branch the default one.

Then you can delete the old one either on the GitLab website or with the command:

git push origin --delete master