anchor.diff:  = Setup web site powered by giblish
   :imagesdir: setup_server_assets
   :numbered:
  +:toc:
   
   == Purpose
   
   To describe how to use giblish as a tool in creating a static web site with documents automatically generated from a git repo.
   
   This text covers two deployment scenarios; one using git hooks only, and one using a combination of git hooks and Jenkins. It has only 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.
  +
  +=== A note about permissions and security
  +
  +These instructions does not give any advice on setting up permissions in a way 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 being security holes of 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.
  +
  +=== A note about server side git hooks
  +
  +git supports hooks in several parts of the sequence of getting changes committed and pushed to a remote repo. This feature is used in both scenarios below to kick-start the HTML document generation when someone pushes a change to the git repository.
  +
  +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 below.
  +
  +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 <your_repo_name>` 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.
   
   == Deploy using git hooks only
   
  
positive.code: 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
  ----
  include::../docgen/scripts/githook_examples/post-update.example[]
  ----
  
negative.code: == 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
  