Debian Codegraph @

docs/src/cdist-install.rst

raw
1 How to install cdist
2 ====================
3
4 Requirements
5 -------------
6
7 Source Host
8 ~~~~~~~~~~~
9
10 This is the machine from which you will configure target hosts.
11
12 * /bin/sh: A POSIX like shell (for instance bash, dash, zsh)
13 * Python >= 3.5
14 * SSH client
15 * sphinx with the rtd theme (for building html docs and/or the man pages)
16
17 Target Hosts
18 ~~~~~~~~~~~~
19
20 * /bin/sh: A POSIX like shell (for instance bash, dash, zsh)
21 * SSH server
22
23 Install cdist
24 -------------
25
26 From git
27 ~~~~~~~~
28
29 Cloning cdist from git gives you the advantage of having
30 a version control in place for development of your own stuff
31 immediately.
32
33 To install cdist, execute the following commands:
34
35 .. code-block:: sh
36
37 git clone https://code.ungleich.ch/ungleich-public/cdist.git
38 cd cdist
39 export PATH=$PATH:$(pwd -P)/bin
40
41 From version 4.2.0 cdist tags and releases are signed.
42 You can get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_.
43 It is assumed that you are familiar with *git* ways of signing and verification.
44
45 You can also get cdist from `github mirror <https://github.com/ungleich/cdist>`_.
46
47 To install cdist with distutils from cloned repository, first you have to
48 create version.py:
49
50 .. code-block:: sh
51
52 ./bin/cdist-build-helper version
53
54 Then you install it with:
55
56 .. code-block:: sh
57
58 make install
59
60 or with:
61
62 .. code-block:: sh
63
64 make install-user
65
66 to install it into user *site-packages* directory.
67 Or directly with distutils:
68
69 .. code-block:: sh
70
71 python setup.py install
72
73 Note that `bin/cdist-build-helper` script is intended for cdist maintainers.
74
75
76 Available versions in git
77 ^^^^^^^^^^^^^^^^^^^^^^^^^
78
79 * The active development takes place in the **master** branch
80 * The released versions can be found in the tags
81
82 Other branches may be available for features or bugfixes, but they
83 may vanish at any point. To select a specific branch use
84
85 .. code-block:: sh
86
87 # Generic code
88 git checkout -b <localbranchname> origin/<branchname>
89
90 So for instance if you want to use and stay with version 4.1, you can use
91
92 .. code-block:: sh
93
94 git checkout -b 4.1 origin/4.1
95
96 Building and using documentation (man and html)
97 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98
99 If you want to build and use the documentation, run:
100
101 .. code-block:: sh
102
103 make docs
104
105 Documentation comes in two formats, man pages and full HTML
106 documentation. Documentation is built into distribution's
107 docs/dist directory. man pages are in docs/dist/man and
108 HTML documentation in docs/dist/html.
109
110 If you want to use man pages, run:
111
112 .. code-block:: sh
113
114 export MANPATH=$MANPATH:$(pwd -P)/docs/dist/man
115
116 Or you can move man pages from docs/dist/man directory to some
117 other directory and add it to MANPATH.
118
119 Full HTML documentation can be accessed at docs/dist/html/index.html.
120
121 You can also build only man pages or only html documentation, for
122 only man pages run:
123
124 .. code-block:: sh
125
126 make man
127
128 for only html documentation run:
129
130 .. code-block:: sh
131
132 make html
133
134 You can also build man pages for types in your ~/.cdist directory:
135
136 .. code-block:: sh
137
138 make dotman
139
140 Built man pages are now in docs/dist/man directory. If you have
141 some other custom .cdist directory, e.g. /opt/cdist then use:
142
143 .. code-block:: sh
144
145 make DOT_CDIST_PATH=/opt/cdist dotman
146
147 Note that `dotman`-target has to be built before a `make docs`-run, otherwise
148 the custom man-pages are not picked up.
149
150 Python package
151 ~~~~~~~~~~~~~~
152
153 Cdist is available as a python package at
154 `PyPi <http://pypi.python.org/pypi/cdist/>`_. You can install it using
155
156 .. code-block:: sh
157
158 pip install cdist
159
160 Installing from source with signature verification
161 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162
163 If you want to install cdist from signed source and verify it, first you need to
164 download cdist archive and its detached signature.
165
166 Get both, *cdist-x.y.z.tar.gz* and *cdist-x.y.z.tar.gz.asc* from release
167 notes of the desired tag *x.y.z* at
168 `cdist git repository <https://code.ungleich.ch/ungleich-public/cdist/-/tags>`_.
169
170 Get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_
171 and import it into GPG.
172
173 Now cdist source archive can be verified using `gpg`, e.g. to verify `cdist-6.2.0`:
174
175 .. code-block:: sh
176
177 $ gpg --verify cdist-6.2.0.tar.gz.asc cdist-6.2.0.targ.gz
178 gpg: Signature made Sat Nov 30 23:14:19 2019 CET
179 gpg: using RSA key 69767822F3ECC3C349C1EFFFEFD2AE4EC36B6901
180 gpg: Good signature from "ungleich GmbH (ungleich FOSS) <[email protected]>" [ultimate]
181
182 Further steps are the same as for `installing from git <cdist-install.html#from-git>`_.