= Publish asciidoc docs in git repos using giblish :imagesdir: setup_server_assets :numbered: :toc: == Purpose To describe how to use giblish as a tool for creating a static web site with documents that are automatically generated each time a contributer push changes to a git repo. If you want to dive straight in and setup one of the scenarios below, jump to <>, otherwise read on for some examples and considerations. === Example usages TBD == Two deployment scenarios This text covers two deployment scenarios; one using a git hook together with a simple (well) shell script, and one using a git hook together with Jenkins. They have both been tested on Linux servers (Ubuntu). Most of the tools and scripts should work on a Windows server as well but might need some tweaking and is, again, not tested. === Git hook and shell script This requires the least number of installed components to work. An overview of the scenario is given below. .Deploy using git hook and shell script image::deploy_with_hooks.svg[] The components needed on the server are: Master Repo:: The common (bare) git repo used by all content writers to push updates to. This repo needs to be setup with a server-side hook (_post-receive_) that are executed by git after each push to the repository. Staging Repo:: A git repo that mirrors the _Master Repo_ and fulfills two functions: . provide a checked-out working tree with the source files (adoc files). . provide a script that uses giblish to publish the adoc files in the working tree as HTML files that reside at a place in the file system where the web server can access them. Web Server:: Apache, Ngnix or other web server that provides clients with HTML pages located somewhere on the file system on the server (eg under /var/www/... ) ==== Considerations Possible advantages:: * it has few dependencies on external tools, only git, giblish and a web server are needed for this to work. * giblish provides templates for both the `post-receive` hook and the `publish_html` script that can be tailored to your specific setup quite easily. Possible drawbacks:: * The hook and publish scripts provided with giblish runs syncronously at each push from a _Doc Writer_ to the _Master Repo_. The time it takes to generate the HTML docs from the adoc source will thus be added to each push to the _Master Repo_. * You need to manually setup the _Staging Repo_ on the server and this is a bit more 'hackish' than letting a build orchestrator tool implement a proper 'build' of your documents. You might for example end up with race conditions if two pushes to the _Master Repo_ are done close in time. * The `publish_html` script provided with giblish only uses the currently checked-out branch on the _Staging Repo_ (typically 'master') to generate the HTML docs. It is non-trivial to add multiple-branch generation to the provided script. === Using Jenkins / git hook combo This setup adds a Jenkins (or similar build orchestrator) installation so it is more tools to setup but offer more flexibility and performance. It is also more robust and thus more 'production friendly'. If you are already doing some kind of development, chances are that you already have this kind of setup as a CI pipeline. .Deploy using Jenkins image::deploy_with_jenkins.svg[] The components needed on the server are: Master Repo:: The common (bare) git repo used by all content writers to push updates to. This repo needs to be setup with a server-side hook (_post-receive_) that are executed by git after each push to the repository. Jenkins instance:: A running instance of Jenkins and one or more defined build jobs that use giblish to build the HTML documents. Web Server:: Apache, Ngnix or other web server that provides clients with HTML pages located somewhere on the file system on the server (eg under /var/www/... ) ==== Considerations Possible advantages:: * Using Jenkins enables a lot of flexibility and scaleability. You can setup multiple jenkins agents to increase performance, you can define many build jobs where each job builds either a particular branch from a particular git repo or many branches from one or many repos. Possible drawbacks:: * You need to be familiar with, and maintain, the Jenkins instance. [[setup_instructions]] == Setup instructions Follow the instructions below to get this running on your server. === Some preliminary notes Permissions and security:: These instructions does not give any advice on setting up permissions in a way that is suitable for your use case. You should however, give this an appropriate amount of consideration. You need to set the permissions so that the relevant tools and scripts can perform their expected tasks without constituting security vulnerabilities on your server. You might want to consider setting up specific user accounts/groups to achieve this but this is outside the scope of this text. Server side git hooks:: git supports several hooks that are executed at different points in the sequence of committing and pushing changes to a repository. This feature is used in both scenarios below to provide the trigger for generating the HTML document. For details on git hooks see https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[this doc]. [[common_setup]] === Initial setup These steps are common to both deployment scenarios. giblish setup:: . Install ruby on the _Server_ (a version no more than 18 months old) . Install giblish on the _Server_ using `gem install giblish` git and gitrepo setup:: . Install git on the _Server_. . Setup the *bare* _Master Repo_ on the _Server_ by either. .. Copy a bare repo you already use to the _Server_ file system. .. Init a new repo using `git init --bare ` somewhere on the _Server_ file system. + NOTE: If you start with an empty, bare, _Master Repo_ on the _Server_, it is a good idea to directly clone it to your local machine, commit some content to the 'master' branch and push the result back to the _Master Repo_. An empty, bare repo does not even contain a 'master' branch from the start and this can lead to some edge cases that complicate things. . Setup the _Staging Repo_ on the _Server_ by cloning the _Master Repo_ to a suitable folder in the _Server_ file system, ex: + .Setup a staging repo in your home folder on the _Server_ ==== cd ~ git clone file:///usr/local/master_repo.git ==== === Setup the git hook and shell script scenario First, follow the steps described in <>. Then proceed with the steps below. script setup:: . Find out where the template scripts for the `post-receive` and the `publish_html.sh` scripts are located by running `gem which giblish`. Strip of the `lib/giblish.rb` from the end of the returned path and `cd` to the resulting folder. There should be a subfolder named `scripts` under which you can find the template scripts somewhere. + .Installation on Ubuntu 16.04 ==== On a server running Ubuntu 16.04, `gem which giblish` returns: /var/lib/gems/2.6.0/gems/giblish-0.7.0/lib/giblish.rb and the template scripts can thus be found somewhere under /var/lib/gems/2.6.0/gems/giblish-0.7.0/scripts ==== . Copy the `publish_html.sh` script to a suitable folder in your _local repo_ on your _local machine_ (e.g. under `/scripts`). . Tweak the configuration variables in the script to fit your use case. . Commit and push script to the _Master Repo_ on the _Server_. . Copy the `post-receive` script to the `hooks` folder in your bare _Master Repo_. . Tweak the configuration variables of the copy to suite your use case. . Set the execute permission using `chmod +x post-receive` stylesheet setup:: The template scripts assume that the the css used to style the generated HTML is located under `/scripts/resources/css` and is called `giblish.css`. To enable a styling of your liking, either create this folder/css file in your repo at that exact place or tweak the `html_publish.sh` script to use another location/css file name for the styling. other tweaking:: You can tweak the `publish_html.sh` script to use other features of giblish/asciidoctor, such as docid's, docinfo support and others. To do this, change the flags and arguments used to invoke giblish from the `publish_html.sh` script accordingly. === Setup the git hook and Jenkins scenario First, follow the steps described in <>. Then proceed with the steps below. TBD ==== Sequence for generating documents The following image shows how the sequence from user commit to generated documents. .Sequence diagram for generating docs from adoc image::Render Documents.png[] [appendix] == Scripts .The giblish `publish_html.sh` template script [%collapsible] ==== [source,bash] ---- include::../scripts/publish_html.sh[] ---- ==== .The giblish `post-receive` template git hook [%collapsible] ==== [source,bash] ---- include::../scripts/hooks/post-receive[] ---- ==== === post-update hook Below is an example of a `post-update` hook that triggers Jenkins jobs after a push to a git repo. This hook should be installed on the server side git repository to trigger Jenkins builds .Example of a git hook triggering Jenkins builds [%collapsible] ==== [source,bash] ---- include::../docgen/scripts/githook_examples/post-update.example[] ---- ==== === Jenkins pipeline script Below is a very basic example of a Jenkins pipeline that triggers giblish to render html and pdf documents located in a specific directory in a git repository. TBD