| 1 |
Bootstrap |
| 2 |
========= |
| 3 |
This document describes the usual steps recommended for a new |
| 4 |
cdist setup. It is recommended that you have read and understood |
| 5 |
`cdist quickstart <cdist-quickstart.html>`_ before digging into this. |
| 6 |
|
| 7 |
|
| 8 |
Location |
| 9 |
--------- |
| 10 |
First of all, you should think about where to store your configuration |
| 11 |
database and who will be accessing or changing it. Secondly you have to |
| 12 |
think about where to configure your hosts from, which may be a different |
| 13 |
location. |
| 14 |
|
| 15 |
For starters, having cdist (which includes the configuration database) on |
| 16 |
your notebook should be fine. |
| 17 |
Additionally an external copy of the git repository the configuration |
| 18 |
relies on is recommended, for use as backup as well as to allow easy collaboration |
| 19 |
with others. |
| 20 |
|
| 21 |
For more sophisticated setups developing cdist configurations with multiple |
| 22 |
people, have a look at `cdist best practice <cdist-best-practice.html>`_. |
| 23 |
|
| 24 |
|
| 25 |
Setup working directory and branch |
| 26 |
---------------------------------- |
| 27 |
I assume you have a fresh copy of the cdist tree in ~/cdist, cloned from |
| 28 |
one of the official URLs (see `cdist quickstart <cdist-quickstart.html>`_ if you don't). |
| 29 |
Entering the command "git branch" should show you "* master", which indicates |
| 30 |
you are on the **master** branch. |
| 31 |
|
| 32 |
The master branch reflects the latest development of cdist. As this is the |
| 33 |
development branch, it may or may not work. There are also version branches |
| 34 |
available, which are kept in a stable state. Let's use **git branch -r** |
| 35 |
to list all branches:: |
| 36 |
|
| 37 |
cdist% git branch -r |
| 38 |
origin/1.0 |
| 39 |
origin/1.1 |
| 40 |
origin/1.2 |
| 41 |
origin/1.3 |
| 42 |
origin/1.4 |
| 43 |
origin/1.5 |
| 44 |
origin/1.6 |
| 45 |
origin/1.7 |
| 46 |
origin/2.0 |
| 47 |
origin/HEAD -> origin/master |
| 48 |
origin/archive_shell_function_approach |
| 49 |
origin/master |
| 50 |
|
| 51 |
So **2.0** is the latest version branch in this example. |
| 52 |
All versions (2.0.x) within one version branch (2.0) are compatible to each |
| 53 |
other and won't break your configuration when updating. |
| 54 |
|
| 55 |
It's up to you to decide which branch you want to base your own work on: |
| 56 |
master contains more recent changes, newer types, but may also break. |
| 57 |
The version branches are stable, but may lack the latest features. |
| 58 |
Your decision can be changed later on, but may result in merge conflicts, |
| 59 |
which you will need to solve. |
| 60 |
|
| 61 |
Let's assume you want latest stuff and select the master branch as base for |
| 62 |
your own work. Now it's time to create your branch, which contains your |
| 63 |
local changes. I usually name it by the company/area I am working for: |
| 64 |
ethz-systems, localch, customerX, ... But this is pretty much up to you. |
| 65 |
|
| 66 |
In this tutorial I use the branch **mycompany**:: |
| 67 |
|
| 68 |
cdist% git checkout -b mycompany origin/master |
| 69 |
Branch mycompany set up to track remote branch master from origin. |
| 70 |
Switched to a new branch 'mycompany' |
| 71 |
cdist-user% git branch |
| 72 |
master |
| 73 |
* mycompany |
| 74 |
|
| 75 |
From now on, you can use git as usual to commit your changes in your own branch. |
| 76 |
|
| 77 |
|
| 78 |
Publishing the configuration |
| 79 |
---------------------------- |
| 80 |
Usually a development machine like a notebook should be considered |
| 81 |
temporary only. For this reason and to enable shareability, the configuration |
| 82 |
should be published to another device as early as possible. The following |
| 83 |
example shows how to publish the configuration to another host that is |
| 84 |
reachable via ssh and has git installed:: |
| 85 |
|
| 86 |
# Create bare git repository on the host named "loch" |
| 87 |
cdist% ssh loch "GIT_DIR=/home/nutzer/cdist git init" |
| 88 |
Initialized empty Git repository in /home/nutzer/cdist/ |
| 89 |
|
| 90 |
# Add remote git repo to git config |
| 91 |
cdist% git remote add loch loch:/home/nutzer/cdist |
| 92 |
|
| 93 |
# Configure the mycompany branch to push to loch |
| 94 |
cdist% git config branch.mycompany.remote loch |
| 95 |
|
| 96 |
# Configure mycompany branch to push into remote master branch |
| 97 |
cdist% git config branch.mycompany.merge refs/heads/master |
| 98 |
|
| 99 |
# Push mycompany branch to remote branch master initially |
| 100 |
cdist% git push loch mycompany:refs/heads/master |
| 101 |
|
| 102 |
Now you have setup the git repository to synchronise the **mycompany** |
| 103 |
branch with the **master** branch on the host **loch**. Thus you can commit |
| 104 |
as usual in your branch and push out changes by entering **git push**. |
| 105 |
|
| 106 |
|
| 107 |
Updating from origin |
| 108 |
-------------------- |
| 109 |
Whenever you want to update your cdist installation, you can use git to do so:: |
| 110 |
|
| 111 |
# Update git repository with latest changes from origin |
| 112 |
cdist% git fetch origin |
| 113 |
|
| 114 |
# Update current branch with master branch from origin |
| 115 |
cdist% git merge origin/master |
| 116 |
|
| 117 |
# Alternative: Update current branch with 2.0 branch from origin |
| 118 |
cdist% git merge origin/2.0 |