Building static websites with Hugo

This documentation covers building a landing page like ecobytes.net or setting up a knowledge repository like docs.ecobytes.net with a static site generator. We chose Hugo which is configured via YAML-files.

Create repositories

Two git repositories within your home git community are being used: one for the theme and the other for content and menu configuration.

  • theme git@gitlab.domain.tld:gitname/project/website-theme.git
  • content + configuration git@gitlab.domain.tld:gitname/project/website.git

Install Hugo and create a new site

http://gohugo.io/getting-started/quick-start/

Install Theme

  1. Fork the chosen Hugo-theme on GitHub.
  2. Create a repository on lab.allmende.io.
  3. Clone the forked theme from GitHub.

    cd themes
    git clone git@github.com:gitname/themename.git myforkedtheme
    cd myforkedtheme
    

Find a new home for your fork on your home git community

For the sake of completeness the repo on GitHub is kept. So that we can push into two repos at once we add them to the new remote “both”.

git remote add both git@github.com:gitname/themename.git
git remote set-url --add --push both git@github.com:gitname/themename.git
git remote set-url --add --push both git@gitlab.domain.tld:gitname/project/website-theme.git

Push to both repos simultaneously is done via:

git push both

Clone existing site

Display an existing site

Verify with by running

hugo serve

and opening http://localhost:1313 in your browser.

Edit existing site

In your tmux session …

tmux
# one pane for
hugo serve
# and another for
vim ...
# with live reload

Deploy to staging

Sometimes one wishes to deploy a site in development to a staging environment. Assuming you know and use Dokku, the repositories are prepared to work with it. You can push your site to it with:

hugo
cd public
git remote add stage dokku@apps.allmende.io:ecobytes-website
# or dokku@apps.allmende.io:ecobytes-documentation
git push -u stage deploy:master
cd ..

Deploy to production

Assuming you wish to deploy master to a production instance, simply issue

./deploy.sh

branching model

  • master
    • untouchable manually, this can only be mutated by Merge Requests
  • stage
    • issue for issues (ideally branch from the issues on gitlab to have them automatically linked)
    • merge request from the branch once finished, review by peers and merge