setupgitbook

Gitbook

The labdocs website is build by a very convenient software called gitbook. It wraps all files in the directory 'labdocs' to a static website, using the table of contents that is given in the file 'SUMMARY.md'.

This website can be viewed and browsed by any standard webbrowser.

In the following I describe, how the gitbook can be installed on a computer and used to build a website. In particular, I explain, how it is set-up to build the labdocs website automatically each time somebody updates the labdocs repository.

structure

All additional files that gitbook needs is a table of contents. It is stored in the labdocs directory and called 'SUMMARY.md'. It marks entries in the menu of the labdocs as markdown links in a markdown list.

# Summary

* [Introduction](README.md)
    * [The team](team.md)
    * [The projects](projects.md)

The index can go as deep as three levels, and it can contain as many chapters and sections as you whish. They will appear as numbered entries in the menu of the gitbook.

build gitbook

To build a static website using gitbook, the software must be installed on the computer (see below). In Linux that is quite easy, as described on the gitbook website.

Then, you can build a static site by typing the following while being in your gitbook directory (labdocs in our case)

gitbook build

This will create or update the sub-directory '_book' with all the content the website needs. The markdown files are parsed into fully functional html files. If you open the file index.html in firefox or chrome the labdocs can be browsed offline.

Gitbook is under development. So, make sure you update it frequently, especially if you encounter any bugs. Bugs that are not yet fixed by an update can be filed here and usually will be resolved within a day.

Just a hint if you apply gitbook to an own project other than labdocs: You should make sure that the '_book' directory is in your .gitignore file. It does not contain original content and does not need to be put under version control.

automated updating of the website

requirements

• node.js
• gitbook

To update the website, the most recent version of gitbook as well as node.js must be installed on the workstation.

build labdocs website

The labdocs repository is hosted as a bare repository on the workstation. For any edits, members of the group can pull and push from and to there.

I set up an automatic deployment line, which means, each time somebody pushs changes into the bare repository, it will execute a bash script that updates the website.

This bash script (see below) does the following:

1. it switches to the /var/git/labdocs/ directory
2. it pulls changes from the parent repo
3. it re-builds the gitbook into the sub-directory _book

The directory /var/git/labdocs/_book now contains the actual website. We need to specify how and where it will be provided by the apache webserver. This is done in the global configuration file of apache at /etc/apache2/httpd.conf. Switch to the apache2 directory and modify the file:

cd /etc/apache2/
sudo vi httpd.conf

Using vi you now can modify the content to contain:

Alias /labdocs /var/git/labdocs/_book
<Directory /var/git/labdocs/_book>
    Order allow,deny
    Allow from all
</Directory>

This specifies an Alias, which is basically a virtual link on the apache root that redirects to the directory where the gitbook lies. The other lines specify, that this directory is accessible by the internet. Other limitations could be specified here (like password access using .htaccess files or IP adress ranges). However, access to the webserver is already regulated on a higher level (through the access limitations of the University and the .htaccess and .htpassword files in the apache root directory).

git post-update hook and bash script

In bare git repositories it is possible to specify actions that happen after each update, so called post-update hooks. For that, create a file called 'post-update' in the directory 'hooks' of the repository (only bare repositories!). This procedure is only allowed to the owner of the repos,which would be the user git. So you need to switch to that user name before (only allowed for admins).

sudo su git
cd path/to/repo/repository.git/hooks/
mk post-update
vi post-update

The empty file opens and should be edited to contain the following:

#!/bin/sh
echo "Deploying Labdocs"

# directory for _book
REPO_DIR="/var/git/repos/labdocs.git"
BOOK_DIR="/var/git/labdocs"

#script
cd $BOOK_DIR
git pull origin master
gitbook build

This bash-script will be executed each time somebody pushes an update to the repository. It will switch to a clone of the repository and build the gitbook.