Provided by: cdist_4.0.0~pre3-2_all bug

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 on is recommended, for use as backup as well as 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 to decide which branch you want to base your own work on: master contains
       more recent changes, newer types, but may also break. The version branches are stable, but
       may lack the latest features. Your decision can be changed later on, but may result in
       merge conflicts, which you will need 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).

AUTHOR

       Nico Schottelius <nico-cdist--@--schottelius.org>
           Author.

                                            04/07/2016                         CDIST-BOOTSTRAP(7)