cdist-backup/doc/man/man7/cdist-bootstrap.text

cdist-bootstrap(7)
==================
Nico Schottelius <nico-cdist--@--schottelius.org>


NAME
----
cdist-bootstrap - setup cdist environment


INTRODUCTION
------------
This document describes the usual steps recommended for a new
cdist setup. It is recommended that you have read and understood
cdist-quickstart(7) before digging into this.


LOCATION
---------
First of all, you should think about where to store your configuration
database and who will be accessing or changing it. Secondly you have to
think about where to configure your hosts from, which may be a different
location.

For starters, having cdist (which includes the configuration database) on
your notebook should be fine.
Additionally an external copy of the git repository the configuration
relies in is recommended, for use as backup as well to allow easy collaboration
with others.

For more sophisticated setups developing cdist configurations with multiple
people, have a look at cdist-best-practice(7).


SETUP WORKING DIRECTORY AND BRANCH
----------------------------------
I assume you have a fresh copy of the cdist tree in ~/cdist, cloned from
one of the official urls (see cdist-quickstart(7) if you don't).
Entering the command "git branch" should show you "* master", which indicates
you are on the **master** branch.

The master branch reflects the latest development of cdist. As this is the
development branch, it may or may not work. There are also version branches 
available, which are kept in a stable state. Let's use **git branch -r**
to list all branches:

--------------------------------------------------------------------------------
cdist% git branch -r
  origin/1.0
  origin/1.1
  origin/1.2
  origin/1.3
  origin/1.4
  origin/1.5
  origin/1.6
  origin/1.7
  origin/2.0
  origin/HEAD -> origin/master
  origin/archive_shell_function_approach
  origin/master
--------------------------------------------------------------------------------

So **2.0** is the latest version branch in this example.
All versions (2.0.x) within one version branch (2.0) are compatible to each
other and won't break your configuration when updating.

It's up to you decide on which branch you want to base your own work:
master contains more recent changes, newer types, but may also break.
The versions branches are stable, but thus may miss the latest features.
Your decision can be changed later on, but may result in merge conflicts,
which you'd have to solve.

Let's assume you want latest stuff and select the master branch as base for
your own work. Now it's time to create your branch, which contains your
local changes. I usually name it by the company/area I am working for:
ethz-systems, localch, customerX, ... But this is pretty much up to you.

In this tutorial I use the branch **mycompany**:

--------------------------------------------------------------------------------
cdist% git checkout -b mycompany origin/master 
Branch mycompany set up to track remote branch master from origin.
Switched to a new branch 'mycompany'
cdist-user% git branch
  master
* mycompany
--------------------------------------------------------------------------------

From now on, you can use git as usual to commit your changes in your own branch.


PUBLISHING THE CONFIGURATION
----------------------------
Usually a development machine like a notebook should be considered
temporary only. For this reason and to enable shareability, the configuration
should be published to another device as early as possible. The following
example shows how to publish the configuration to another host that is
reachable via ssh and has git installed:

--------------------------------------------------------------------------------
# Create bare git repository on the host named "loch"
cdist% ssh loch "GIT_DIR=/home/nutzer/cdist git init"
Initialized empty Git repository in /home/nutzer/cdist/

# Add remote git repo to git config
cdist% git remote add loch loch:/home/nutzer/cdist 

# Configure the mycompany branch to push to loch
cdist% git config branch.mycompany.remote loch

# Configure mycompany branch to push into remote master branch
cdist% git config branch.mycompany.merge refs/heads/master

# Push mycompany branch to remote branch master initially
cdist% git push loch mycompany:refs/heads/master
--------------------------------------------------------------------------------

Now you have setup the git repository to synchronise the **mycompany**
branch with the **master** branch on the host **loch**. Thus you can commit
as usual in your branch and push out changes by entering ***git push***.


UPDATING FROM ORIGIN
--------------------
Whenever you want to update your cdist installation, you can use git to do so:

--------------------------------------------------------------------------------
# Update git repository with latest changes from origin
cdist% git fetch origin

# Update current branch with master branch from origin
cdist% git merge origin/master

# Alternative: Update current branch with 2.0 branch from origin
cdist% git merge origin/2.0
--------------------------------------------------------------------------------


SEE ALSO
--------
- cdist(1)
- cdist-tutorial(7)


COPYING
-------
Copyright \(C) 2012 Nico Schottelius. Free use of this software is
granted under the terms of the GNU General Public License version 3 (GPLv3).