Week 1

Setting up a Class Archive Site

Making a Fab Academy class site and pushing to the archive with Git

My previous post was getting pretty long, so I omitted a chunk of my background related to coding and development. To keep the story short, I have been making websites, apps and applets (such as PushMePullMe) as side projects since 2004. My programming skills are completely self-taught, so may be patchy in places!

Cloning from the archive


As part of the Fab Academy right of passage, all students must create a website (like this one) hosted on the Fab Academy Archive. Each participating Lab has it’s own code repository, which is . Getting your content onto the archive is as simple as uploading to the Lab repository. Webhooks take care of the rest, to automatically integrate changes in the repository into the Fab Academy Archive.

I currently use Git almost exclusively for version control, so was happy to hear Fab Academy has moved to Git this year as it’s version control system of choice! If you’re just getting starting with Git, I recommend checking out Atlassian’s Git tutorials. For software projects, I favour the Gitflow workflow and like to use SourceTree as a Git Client for visualising more complex repositories.

The first step towards getting content on the archive, is to make a local copy (clone) of the remote repository. To do this, you need to be added to the repository as a developer. Once that’s taken care of, you can log in to the GitLab interface (git.fabacademy.org/fabacademy2016/< Lab Name >) using you fablabs.io credentials.

Authentication is needed to push content to the repository, so an SSH key must be generated and saved in the GitLab interface. Generated an SSH key from the terminal:

ssh-keygen -t rsa -C "<your email address>"

The output key needs to be saved in GitLab. I had a bit of trouble finding the SSH keys section in GitLab, so for reference, go to your user profile > Profile Settings > SSH Keys. Copy the key you generated and add it using the Add SSH Key button.

Adding SSH keys to GitLab Finding where to put SSH keys in GitLab

Once you have your SSH key set up, we’re ready to clone the repository:

git clone git@git.fabacademy.org:fabacademy2016/<Lab Name>.git

Setting up my archive site


For speed, I set up Aalto Fablab’s class page using straight html and css, with no javascript (I used CSS animation to draw attention to the down arrow). I might add a touch of js later to add a parallax scrolling effect.

Aalto Fablab's fab Academy 2016 class page Aalto Fablab’s fab Academy 2016 class page

I used .svg images throughout so I can resize elements without a loss in quality. This will be very handy when I get to sorting out a responsive layout for mobile and other devices.

The down arrow’s attention-seeking bounce is implemented with CSS animation:

  @keyframes bounce {
    0%, 8%, 16%, 100% {
      transform: translateY(0);
    }
    4%, 12% {
      transform: translateY(-15px);
    }
  }

  .arrow {
    padding-top: 80px;
    animation-name: bounce;
    animation-duration: 6s;
    animation-iteration-count: infinite;
  }

For my own project pages (the ones you are reading now), I opted for a static site generator. Static site generators take template files, reusable sections of code (partials) and text files and builds them into html. In this way there are no databases to maintain and no database queries, so it keeps this simple and fast!

These days there are dozens of static site generators out there (see staticsitegenerators.net for an extensive list). I’ve tried a few before, but decided to go for Wintersmith this time since it seemed simple, has an active GitHub repository and comes pre-packaged with jade as a templating engine, less as a CSS preprocessor and takes markdown for content - all of which I am familiar with.

Wintersmith is super easy to install and set up - it also comes with a basic theme and example articles, so you can be up and running very quickly. In spiral development style, I initially used the default theme just to get some kind of content onto the archive.

First, install Wintersmith with npm (node package manager):

$ npm install wintersmith -g

Then create a new project (remember to replace < path > with the location you want your new project to be generated):

$ wintersmith new <path>

To view the site, change directory to the project root and start previewing:

$ cd <path>
$ wintersmith preview

Pushing to the archives


Now I had the bones of a website, it was time to push it up to the repository and on to the archive.

Add the files you want to commit to the staging area (use -A to add all changes):

$ git add -A

Check which files are staged for commit using git status:

$ git status

You should see a list of files which have been added, deleted or changed. If you are happy, make a commit:

$ git commit -m "<your commit message goes here>"

At this point the changes have been committed to the local repository. Now we need to sync those changes with the remote repository by pushing:

$ git push origin master

origin is the (remote) repository and master is the branch we are pushing to.

A visit to the archive site (archive.fabacademy.org/archives/2016/< Lab Name >) and a page refresh should reveal the fruits of your command line labour!

TODOs

☑ Make a website and describe how it was done
☑ Introduce myself (see Meet Charlie)
☑ Document steps for uploading files to the class archive
☑ Push content to the class archive

Links

Fab Academy 2016 - Project Management