# -*- mode: org; mode: auto-fill; -*-
#+STARTUP:	showeverything

* Org Converge
** Description

  This attempts to be an experiment of using Org mode syntax to
  describe, configure and setting up something, borrowing some ideas
  of what is possible to do with tools like =chef-solo=, =puppet=,
  =ansible=, etc...

** Motivation

  The Org babel syntax has proven to be flexible enough to produce
  /reproducible research/ papers. Then, I believe that configuring and setting up
  a server for example is something that could be also be done using
  the same syntax, given that /converging/ the configuration is something
  that one ought to be able to reproduce.

** Usage

   To run the blocks in parallel:

#+begin_src sh
org-converge path/to/setup-file.org
#+end_src

   Or sequentially:

#+begin_src sh
org-converge path/to/setup-file.org --runmode=sequential
#+end_src

** Quick example

   The following is an example of running 3 processes
   in parallel by defining them as code blocks from 
   an Org mode file:

#+begin_src sh
  ,#+TITLE: Running Org babel processes in parallel
   
  * Print with different languages
   　
  ,#+name: hello_from_bash
  ,#+begin_src sh :shebang #!/bin/bash
  while true; do echo "hello world from bash"; sleep 1; done
  ,#+end_src
  　 
  ,#+name: hello_from_ruby
  ,#+begin_src ruby :shebang #!/usr/local/bin/ruby
  $stdout.sync = true
  loop { puts "hello world from ruby" ; sleep 1 }
  ,#+end_src
  　 
  ,#+name: hello_from_python
  ,#+begin_src python :shebang #!/usr/bin/python
  import time
  import sys
  for i in range(0,100):
    print "hello world from python"
    sys.stdout.flush()
    time.sleep(1)
  ,#+end_src   
#+end_src

  We store this in a file named =hello.org= and then run it as follows:

#+begin_src sh
org-converge hello.org
#+end_src

  This would produce an output similar to the following:

#+begin_src sh
I, [2014-04-17T23:48:44.663545 #1710]  INFO -- : Tangling 0 files...
I, [2014-04-17T23:48:44.663698 #1710]  INFO -- : Tangling succeeded!
I, [2014-04-17T23:48:44.664829 #1710]  INFO -- : Running code blocks now! (4 runnable blocks found in total)
I, [2014-04-17T23:48:44.762899 #1710]  INFO -- : hello_from_bash       (1711) -- started with pid 1711
I, [2014-04-17T23:48:44.808717 #1710]  INFO -- : hello_from_ruby       (1712) -- started with pid 1712
I, [2014-04-17T23:48:44.837878 #1710]  INFO -- : hello_from_python     (1713) -- started with pid 1713
I, [2014-04-17T23:48:44.878336 #1710]  INFO -- :                       (1714) -- started with pid 1714
I, [2014-04-17T23:48:44.879284 #1710]  INFO -- : hello_from_bash       (1711) -- hello world from bash
I, [2014-04-17T23:48:44.882778 #1710]  INFO -- : hello_from_ruby       (1712) -- hello world from ruby
I, [2014-04-17T23:48:44.883637 #1710]  INFO -- : hello_from_python     (1713) -- hello world from python
I, [2014-04-17T23:48:45.778681 #1710]  INFO -- : hello_from_bash       (1711) -- hello world from bash
I, [2014-04-17T23:48:45.792321 #1710]  INFO -- : hello_from_ruby       (1712) -- hello world from ruby
I, [2014-04-17T23:48:45.882020 #1710]  INFO -- : hello_from_python     (1713) -- hello world from python
I, [2014-04-17T23:48:46.787106 #1710]  INFO -- : hello_from_bash       (1711) -- hello world from bash
I, [2014-04-17T23:48:46.793347 #1710]  INFO -- : hello_from_ruby       (1712) -- hello world from ruby
I, [2014-04-17T23:48:46.883511 #1710]  INFO -- : hello_from_python     (1713) -- hello world from python
I, [2014-04-17T23:48:47.794846 #1710]  INFO -- : hello_from_ruby       (1712) -- hello world from ruby
I, [2014-04-17T23:48:47.796387 #1710]  INFO -- : hello_from_bash       (1711) -- hello world from bash
I, [2014-04-17T23:48:47.884196 #1710]  INFO -- : hello_from_python     (1713) -- hello world from python
#+end_src

** How it works

  Org Converge uses an liberally extended version of Org Babel
  features in order to give support for converging the configuration
  of a server.

  For example, using Org Babel and macros we can easily spread config
  files on a server by writing the following on a ~server.org~ file.

  #+begin_src sh
    ,#+begin_src yaml :tangle /etc/component.yml
    multitenant: false
    status_port: 10004
    ,#+end_src
  #+end_src

  And then configure it by running it as follows, (considering we have
  the correct permissions for tangling at =/etc/component.yml=): 

  #+begin_src sh
  sudo org-converge server.org
  #+end_src

  Next, let's say that we no only one want to set the configured templates,
  but that we also want to install some packages. In that case, we
  should be able to do the following:

  #+begin_src sh
  ,* Configuring the component

  ,#+begin_src yaml :tangle /etc/component.yml
  multitenant: false
  status_port: 10004
  ,#+end_src  
　
  ,* Installing the dependencies
　
  Need the following so that ~bundle install~ can compile 
  the native extensions correctly.
　
  ,#+begin_src sh
  apt-get install build-essentials -y
  ,#+end_src
　
  Then the following should work:
　
  ,#+begin_src sh
  cd project_path
  bundle install
  ,#+end_src
  #+end_src

  As long as the repo has been already checked out in the directory, 
  the previous example will succeed. 

  More practical examples can be found [[https://github.com/wallyqs/org-converge/tree/master/examples][here]], more will be added as
  long as dogfooding from this goes well.

** Contributing

  The project is in very early development at this moment, but if you
  feel that it is interesting enough, please create a ticket so start
  the discussion.