VSHNs public employee handbook.vshn.ch is created and published using GitLab and GitLab pipelines. In this talk, Aarno will show you the process from Asciidoc sources in the Git repo all the way to being deployed on APPUiO.ch Kubernetes.

1. 1
handbook.vshn.ch
Gitlab Meetup 2021-09-16
Aarno Aukia, CTO

2. 2
Agenda
● About handbook.vshn.ch
● Gitlab CI process to test,
build & deploy
● Local development
● Merge requests for
non-engineers
● Publishing

3. ● The public VSHN employee handbook
● 2019-05-17 first commit
● 2019-07-25 first public version
● 1440 commits, 428 merge requests
● 134 web pages, 496 pages PDF
https://handbook.vshn.ch
3

4. ● 10922 lines of AsciiDoc (similar to
Markdown)
● Processed using Antora and AsciiDoctor
○ Result: HTML, PDF, EPUB, Manpage
○ Same setup used for 7 sites
● Git repo of handbook is not public
because MR discussions are not public
● public: app catalog, managed services
● All tools are open source software
Behind the scenes
4

5. Building the handbook
5

6. Build pipeline
6

7. Build pipeline
7

8. ● Language style check: https://github.com/vshn/vale
● Antora: https://github.com/vshn/antora-docker
● VSHN template: https://github.com/vshn/antora-ui-default
● PDF: https://github.com/vshn/asciidoctor-pdf
● EPUB: https://github.com/vshn/asciidoctor-epub3
● Full text indexer:
https://github.com/vshn/antora-indexer-cli
● Production base image:
https://github.com/vshn/antora-nginx
● Search base image:
https://github.com/vshn/embedded-search-engine
Links to tools
8

9. ● Work in a feature branch from “develop”
● make preview
○ auto-reloads on source edits at
http://localhost:2020 using
https://github.com/vshn/antora-preview
● make check
○ runs basic checks before commit/CI
● Create MR from feature branch to
“develop” to review/discuss
Local development
9

10. ● After some training, even non-engineers
can comment, propose changes, and edit
files in merge requests
● Demo: example
MR for non-engineers
10

11. ● Complement Changelog since last release
● Create MR from develop to master
● Merge to master -> prod deployment
● Create template Changelog entry for next
release
Publishing
11

12. VSHN helps
software developers
to run their
applications anywhere.
12

13. Thank you.
https://vshn.ch/
VSHN is the leading Swiss partner for
DevOps, Kubernetes & Cloud Operations.
How can we help you?
VSHN AG - Neugasse 10 - CH-8005 Zurich - Switzerland - +41 44 545 53 00 - https://vshn.ch/ - info@vshn.ch
13