Skip to content

Week 1

Principles and Practices, Project Management

Summary

This week we were tasked to setup this website and document how we did it.

Approach

This week my approach is to really focus on the advice from the student boot camp and focus on spiral development and supply-side time management. My natural tendency is to get distracted by glitter and loose the sight of what I'm trying to achieve. To prevent this I looked at my calendar and set aside blocks of time, then divided the assignment tasks over these blocks. To makes sure I wouldn't over-engineer or put the cart before the horse, I decided not to do any styling this week. Focusing on spiral development I'm going to first see what content I produce each week, before deciding on a storytelling format and design.

What this means for now is that I'm focusing on writing content in markdown language, practicing my storytelling and documentation skills, while not thinking too much about the presentation of that markdown. Once I have a better understanding of how I want to tell my story I will start thinking about how to present that. Since I have a background as a web-developer, I'll probably end up wanting more DOM control and a more plain HTML with basic css design. Working in markdown for now will allow me to easily port the content into a different presentation when needed. I also have some ideas for a staging/styling branch deploy pipeline, but I'll implement that only if and when needed; YAGNI.

So what does this mean for my website setup? I'm going to start by installing MkDocs and Material for MkDocs so I can focus on writing the documentation with an existing presentation theme.

Assignment

Student agreement

Signed, committed and pushed to my repository.

Git tutorial

Although I've been managing version control and changes through Git and even Subversion (SVN) over 15 years, I haven't used it much in the past few years. A few weeks back whilst working through the first commands again I noticed how my memory of specific commands had gotten rusty, but my understanding of git's underlying principles was pretty solid. By using git -h to browse through the available commands, flags and arguments I found my way around pretty quickly. This week I noticed a meme being shared on our Fab Academy 2026 Mattermost meme channel :) and remembered how frustrating wrapping my head around git had been al those years back.

I remember that one talk that changed it al, at Codemotion Amsterdam 2016 Steve Smith from Atlassian gave the talk on Git. So I decided to rewatch the latest recording of it and share it with my classmates.

Setting up website

SSH keys

To copy my repository locally (clone) and push changes back to the repository you have to authenticate with Git. There are two ways to do this, HTTPS en SSH. I opted for SSH since this means I don't have to manually type my password every time I run a Git command.

Fab Academy runs a self hosted version of (Gitlab)[https://about.gitlab.com/], but setting up an SSH key works the same way irregardless of where it's hosted. Setting up an the SSH key should've gone smoothly, had it not been for an .shh typo I overlooked. I used ssh -vvv -T git@gitlab.fabcloud.org to debug the connection, but stared at the log for the longest time before feeding it to ChatGPT, who immediately caught the typo. Welcome to GitLab, @heleen-emanuel!, now we were cooking.

Installing packages

After cloning the repository I threw out most of the contents and set up a Python virtual environment to keep the packages installed for this project isolated from my local machine and mimic the server setup more closely. I proceeded to install MkDocs and Material for MkDocs through (pip)[https://pypi.org/project/pip/] and test my setup locally. One issue I ran into was that mkdocs serve wouldn't reload the pages for me whenever I made a change to the code; a feature that should work out of the box.

Assuming this to be an issue I caused myself I ran serve with the verbose flag and look at all the installed packages. After some testing and checking of versions, I couldn't find the issue and decided to feed the log to ChatGPT, again. Turns out there was a known breakage I couldn't have known about.

After downgrading the click package as ChatGPT recommended I proceeded to run pip freeze > requirements.txt, this writes all the installed packages their version to requirements.txt. I can now tell the server to use this file when running pip install so it uses the same versions of the packages I'm locally running.

When the local setup finally seemed to work with only minor content changes I committed the changes and pushed them to the repository. Now my changes were in Gitlab, but not on the server yet, therefor I have to configure a deploy pipeline. Basically some commands Gitlab runs to build HTML from my markdown files and put these in the right folder so you can access them through this url.

Deploy pipeline

Next up it was time to setup the CI/CD pipeline. The default setup Julian from Fab Academy supplied us with contains a .gitlab-ci.yml which copies the contents of a folder public to something called Gitlab Pages. Because I installed packages locally I need the server to do the same. First of I need to set the image to a Python version to make sure the server can install Python packages at all. Then I should add some scripting steps to install the packages and build the HTML files from my markdown files.

One issue I ran into is that MkDocs by default build into a folder site, while Gitlab by default deploys from a folder called public. So I tried updating the path from public to site in gitlab-ci.yml, committed the changes and... watched the pipeline fail. Never mind, new approach: make MkDocs build into public by setting site_dir: public in MkDocs YAML config. Commit, push and success!

Content creation

The requirements this week state that we need to add some content, mainly some information about ourselves, our final project idea. We're also required to document weekly, what did we do and how did we do it? Both Rico and Henk recommended us to setup a template for the documentation each week. I took inspiration from Rico's slides #22 & #23 and Henk's suggestions in the local lesson and started a template here. Using spiral development I plan to iterate on this next week and may change the format of my documentation over the course for productivity and readability reasons.

Upload to class archive.

To make sure you can read all this, I've committed and pushed all my changes to the Git repository and checked that the deploy pipeline didn't fail.

Final project

Finally it was time to start on my final project sketch and description, you can see my plans here.

What would I do differently

  • from the shh typo I was reminded again to either copy or use auto complete for paths, typing them from memory can cause you a lot of time
  • keep up the focus on mvp, cause with only a week deadline debugging can easily be time sink
  • ask ChatGPT sooner when debugging

Further exploration

  • update repo readme
  • change look and feel through default features
  • make images prettier, annotate, caption and copyright them (accessibility)
  • look into material's blog plugin
  • fix nav bar structure and links to template and final project on this page