cdist/docs/src/cdist-install.rst
Darko Poljak d5ac9ea348 Docs: install from source, verify signature
Add chapter for installing from source with signature verification.
Resolves #795.
2019-12-08 16:35:41 +01:00

182 lines
4.5 KiB
ReStructuredText

How to install cdist
====================
Requirements
-------------
Source Host
~~~~~~~~~~~
This is the machine from which you will configure target hosts.
* /bin/sh: A posix like shell (for instance bash, dash, zsh)
* Python >= 3.2
* SSH client
* sphinx (for building html docs and/or the man pages)
Target Hosts
~~~~~~~~~~~~
* /bin/sh: A posix like shell (for instance bash, dash, zsh)
* SSH server
Install cdist
-------------
From git
~~~~~~~~
Cloning cdist from git gives you the advantage of having
a version control in place for development of your own stuff
immediately.
To install cdist, execute the following commands:
.. code-block:: sh
git clone https://code.ungleich.ch/ungleich-public/cdist.git
cd cdist
export PATH=$PATH:$(pwd -P)/bin
From version 4.2.0 cdist tags and releases are signed.
You can get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_.
It is assumed that you are familiar with *git* ways of signing and verification.
You can also get cdist from `github mirror <https://github.com/ungleich/cdist>`_.
To install cdist with distutils from cloned repository, first you have to
create version.py:
.. code-block:: sh
./bin/build-helper version
Then you install it with:
.. code-block:: sh
make install
or with:
.. code-block:: sh
make install-user
to install it into user *site-packages* directory.
Or directly with distutils:
.. code-block:: sh
python setup.py install
Note that `bin/build-helper` script is intended for cdist maintainers.
Available versions in git
^^^^^^^^^^^^^^^^^^^^^^^^^
* The active development takes place in the **master** branch
* The released versions can be found in the tags
Other branches may be available for features or bugfixes, but they
may vanish at any point. To select a specific branch use
.. code-block:: sh
# Generic code
git checkout -b <localbranchname> origin/<branchname>
So for instance if you want to use and stay with version 4.1, you can use
.. code-block:: sh
git checkout -b 4.1 origin/4.1
Building and using documentation (man and html)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to build and use the documentation, run:
.. code-block:: sh
make docs
Documentation comes in two formats, man pages and full HTML
documentation. Documentation is built into distribution's
docs/dist directory. man pages are in docs/dist/man and
HTML documentation in docs/dist/html.
If you want to use man pages, run:
.. code-block:: sh
export MANPATH=$MANPATH:$(pwd -P)/docs/dist/man
Or you can move man pages from docs/dist/man directory to some
other directory and add it to MANPATH.
Full HTML documentation can be accessed at docs/dist/html/index.html.
You can also build only man pages or only html documentation, for
only man pages run:
.. code-block:: sh
make man
for only html documentation run:
.. code-block:: sh
make html
You can also build man pages for types in your ~/.cdist directory:
.. code-block:: sh
make dotman
Built man pages are now in docs/dist/man directory. If you have
some other custom .cdist directory, e.g. /opt/cdist then use:
.. code-block:: sh
make DOT_CDIST_PATH=/opt/cdist dotman
Note that `dotman`-target has to be built before a `make docs`-run, otherwise
the custom man-pages are not picked up.
Python package
~~~~~~~~~~~~~~
Cdist is available as a python package at
`PyPi <http://pypi.python.org/pypi/cdist/>`_. You can install it using
.. code-block:: sh
pip install cdist
Installing from source with signature verification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to install cdist from signed source and verify it, first you need to
download cdist archive and its detached signature.
Get both, *cdist-x.y.z.tar.gz* and *cdist-x.y.z.tar.gz.asc* from release
notes of the desired tag *x.y.z* at
`cdist git repository <https://code.ungleich.ch/ungleich-public/cdist/-/tags>`_.
Get GPG public key used for signing `here <_static/pgp-key-EFD2AE4EC36B6901.asc>`_
and import it into GPG.
Now cdist source archive can be verified using `gpg`, e.g. to verify `cdist-6.2.0`:
.. code-block:: sh
$ gpg --verify cdist-6.2.0.tar.gz.asc cdist-6.2.0.targ.gz
gpg: Signature made Sat Nov 30 23:14:19 2019 CET
gpg: using RSA key 69767822F3ECC3C349C1EFFFEFD2AE4EC36B6901
gpg: Good signature from "ungleich GmbH (ungleich FOSS) <foss@ungleich.ch>" [ultimate]
Further steps are the same as for `installing from git <cdist-install.html#from-git>`_.