Literate DevOps

Even as on advocate of automation I see the need of taking notes of your systems. Legacy systems and stuff that cannot be automated for whatever reason. Using a logbook in plain text is a good choice.

If you call this file LOGBOOK.org and use Emacs you can save a lot of hassle. Besides beeing a good editor Emacs is capable of running shells. org-mode gives you a markup language and the capability of executing code blocks in that shell.

Got your attention? Then lets dive in an example:

# -- org-export-babel-evaluate: nil;  --
#+SETUPFILE: ~/git/github/org-html-themes/setup/theme-bigblow.setup
LOGBOOK of test environment
* 2015-02-06
** Login to test system
   [2015-06-02 Tue 16:43]

*** Create a session for Emacs:

#+BEGIN_SRC sh :session client
ssh root@192.168.152.130
#+END_SRC


*** install etckeeper
   [2015-06-02 Tue 16:43]

Before doing anything else make sure etckeeper is installed and
configured:

#+BEGIN_SRC sh :session client :results verbatim drawer
yum -y install etckeeper
etckeeper init
etckeeper commit "initial commit"
#+END_SRC

#+RESULTS:
:RESULTS:
yum -y install etckeeper
Failed to set locale, defaulting to C
Loaded plugins: fastestmirror, presto, security
Determining fastest mirrors
 * base: mirror.23media.de
 * epel: mirror.de.leaseweb.net
 * extras: mirror.23media.de
 * updates: mirror.23media.de
Setting up Install Process
Resolving Dependencies
Running transaction check
Package etckeeper.noarch 0:1.18.1-2.el6 will be installed
etckeeper init
Finished Dependency Resolution
etckeeper commit "initial commit"

Dependencies Resolved

==============================================================================
 Package            Arch            Version                 Repository     Size
==============================================================================
Installing:
 etckeeper          noarch          1.18.1-2.el6            epel           40 k

Transaction Summary
==============================================================================
Install       1 Package(s)

Total download size: 40 k
Installed size: 64 k
Downloading Packages:
Setting up and reading Presto delta metadata
Processing delta metadata
Package(s) data still to download: 40 k

etckeeper-1.18.1-2.el6.noarch.rpm                        |  40 kB     00:00
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
:END:

We are using a time stamp in the format YYYY-MM-DD as a headline.

Each headline sublevel contains a time stamp of creation.

The first task is always to create a session - in this case called client.

Then we can describe the tasks and check the commands twice before hitting <ctrl> and <c> twice to execute the source block.

As a bonus we are also getting a result set.

There are times when we have to do almost the same tasks on multiple systems. Just copy a block, edit it a little bit and run the same commands.

With this little snippet you can even speed up things by hitting <ctrl> <c> followed by <N>.

No problem if we have to double check between each step: Split your screen and have LOGBOOK.org in one frame and the client session in the other. Switch to the shell to verify configfiles before running sed lines to alter the files on the other system.

If we find tasks that need to be done later your LOGBOOK.org is the perfect place for the to-do list. org supports it.

You have an upcoming night shift to maintain a database? Nobody is wide awake at 3am. Prepare all tasks with marginalia in advance. Add checkboxes if you need them:

** TODO install frontend update
  [2015-06-02 Tue 17:01]
- [X] stop webserver
- [ ] backup database
- [ ] install update
- [ ] run test script
- [ ] start webserver

Because it’s just plain text we might store it in some git repository.

And at the end: export your LOGBOOK.org to a beautiful LOGBOOK.html

Since when was documentation so easy and convenient?