University of Turku

Capstone

How to capstone

Documentation

Motivation, why are we doing this

This website serves as a gallery of previous projects done on the capstone course to serve you beyond study points: If your CV is lacking in projects, you can reference to this course in your CV. You can also use this website to link to your CV/LinkedIn/personal website.

Additionally, here you will also learn the basic workflow of GitLab if not already familiar with it. You will work with a live system that has both staging and production environments that are actually being used. You can view and study the whole pipeline and system from start to finish under the capstone gitlab group. This is not a golden example, but a functional one currently in use. Extra credits (unfortunately, not really) if you can help improve the capstone website or this documentation in any way.

In summary: Markdown files go in, a website comes out.

Remember to ask help from other teams also if you are stuck. This is not a competition!

Adding new projects

Tools needed: git, a text editor

Reference material:

First, fork this repository and clone your forked repository to your local machine (see reference material or ask someone who knows how to use git).

  1. Go to the projects/ folder and copy some good project and rename the copy to something meaningful for your project (lowercase without spaces preferred), this name will show up on the URL of your project.

  2. Modify the en.md within your copy to include your content.

    At the very least en.md is needed, but "fi" or "sv" versions can be written too. Experimental cn.md can also be written for Chinese version. Please try! The md-files contain Markdown, which is a way to produce documents. See the link for examples how to write various elements in it, like images or links or bullet points. You can even use HTML if needed.

  3. Add thumb.jpg. It is the image for your project that is shown on the project pages. It gets resized down for thumbnails, so size should not matter.

    Sorry, no png allowed yet (feel free to add support for this if you feel brave)

  4. Modify meta.yaml. It contains the project's title and authors list among other things.

    You can validate the configuration by running the builder (instructions below), but you can copypaste the configuration here to see that it is at least valid.
    Also remember to provide an adequate length description in the yaml file.

  5. If you need additional images you can put them under projectname/img/ folder. These images do not get resized. You can also link to images on other services.

  6. commit changes, push to your repository

  7. Create a merge request on gitlab to the master branch

  8. Wait for approval on the merge request (this has not been automated)

    Alternatively: This repository contains everything to build the whole capstone website so you can also test locally on Linux. See below for some help.

  9. Check the staging website for how your project looks like now

  10. Do necessary changes and make a new merge request.

  11. Done!

    The staging website will be merged into production by the website maintainers, eventually.

For the website maintainer

Each time someone has submitted a merge request:

  1. Accept merge requests here

    Now the people who merged can see their pages live in the staging website
    If a merge conflicts, then use the help of a git wizard

  2. Wait/Check that the build finishes properly: build status

    If it shows failed, consult a continuous integration/git wizard.

  3. Check that the staging website looks OK.

  4. OPTIONAL: Wait for everyone to check out the staging website

  5. Create a merge request from staging into production and accept it.

  6. Check that production build did not fail: build status

Changing highlighted projects:

  • Each project has a "yaml" file, which either contains or does not contain the line "highlight_project: true", for example here

  • Remove highlights by editing the yaml file of each highlighted project you want to remove

  • ... and other way around, add the mentioned line at the top of the yaml file to highlight a project

Repository content

  • build/ (This is where the website is generated, initially empty)

  • projects/ (each project is a folder)

    • project_name
      • en.md (Content text in markdown for the project's page. fi.md for finnish version, etc.)
      • en.mustache (Bare version without markdown, needs to be defined manually in meta.yaml. )
      • fi.md (This file is where one types the text for a project)
      • meta.yaml (Metadata for the project, such as authors, title, year, etc)
      • css/
        • asd123.css (These folders (css/js/img) get merged with the rest of the folders on build. NOTE NAME CONFLICTS are possible because of this.)
  • pages

    • index
    • logic.lua (This file contains logic for the pages.More details below)
    • en.md
    • meta.yaml (Similar to what projects have, but you can define no markdown or choose the source file to be .mustache for example.)
  • initializr (contains assets such as js/css/header/footer stuff, gets merged with the website)

Installation

First, clone the git repo. On a Ubuntu server you can do this:

sudo apt-get install luajit luarocks libmagickwand-dev
sudo luarocks install lustache lunamark magick markdown xml yaml luapress dkjson date cosmo i18n inspect luafilesystem

Running

For hosting you need to define in constants.lua

consts.website_root         = "http://127.0.0.1/build/"
consts.website_suffix_html  = false

The root is used for absolute URLs in canonical refs and in ATOM feed.

The suffix is used to determine whether links have to be suffixed with .html or not.

To run the generator just run the following command and the resulting website should be built onto build/ folder

luajit main.lua 

Use your favorite webserver to serve the content.

logic.lua

This file contains logic for the pages in Lua programming language (it is relatively simple scripting language, easier than python I would say). Contact page's form is defined here for example. Index page's highlights is coded here too.

Misc

How to add menu buttons

The menu buttons are located in main.lua for now.

How to highlight project

Project highlights are done in each project's meta.yaml

Why did you not use jekyll/hexo (or wordpress)

Jekyll and Hexo are both static website generators that more or less want to generate blog posts. Their complexity was too great for this small a project and I felt like fighting against the framework, not with the framework. Multilingual support also felt lacking.

If you are a Jekyll guru you may be able to port this website easily to it and have everything work simple. The projects are in standard markdown format and the standard familiar yaml is in a separate file.

Wordpress was not used because that requires a lot from the hosting provider plus maintenance would be needed to keep the website safe.

Components used