Debian Codegraph @

docs/src/cdist-bootstrap.rst

raw
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