ungleich-public
/
cdist-web
6
0
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request 'Refresh website content, add contrib docs to the generation pipeline' (#1) from fnux/cdist-web:master into master 

Reviewed-on: #1
master
zhaw-linthal 2022-06-03 10:55:42 +00:00
parent a68a2efa1b 58d28147dd
commit 0c0a639969
14 changed files with 103 additions and 447 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
Makefile
View File

@ -7,14 +7,19 @@ WEBSITE_REMOTE_DIR=/home/services/www/nico/www.cdi.st/www/
WEBSITE_MANUALS_DIR="$(WEBSITE_SRC_DIR)/extra/manual"
CDIST_DIR=../cdist
CDIST_CONTRIB_DIR=../cdist-contrib
CDIST_DOCS_DIR="$(CDIST_DIR)/docs"
CDIST_CONTRIB_DOCS_DIR="$(CDIST_CONTRIB_DIR)/docs"
CDIST_HELPER="$(CDIST_DIR)/bin/cdist-build-helper"
CDIST_CHANGELOG_VERSION=$(shell $(CDIST_HELPER) changelog-version)
CDIST_CHANGELOG_FILE="$(CDIST_DOCS_DIR)/changelog"
CDIST_DOCS_HTML_DIST_DIR="$(CDIST_DOCS_DIR)/dist/html"
CDIST_CONTRIB_DOCS_HTML_DIST_DIR="$(CDIST_CONTRIB_DOCS_DIR)/dist/html"
CDIST_MAKE_VERSION=make -C "$(CDIST_DIR)" version
CDIST_MAKE_HTML=make -C "$(CDIST_DIR)" html
CDIST_CONTRIB_MAKE_HTML=make -C "$(CDIST_CONTRIB_DIR)" html
CDIST_CLEAN_HTML=make -C "$(CDIST_DOCS_DIR)/src" clean
CDIST_CONTRIB_CLEAN_HTML=make -C "$(CDIST_CONTRIB_DOCS_DIR)/src" clean
SPHINXH=make -C $(WEBSITE_SRC_DIR) html
SPHINXC=make -C $(WEBSITE_SRC_DIR) clean
@ -51,8 +56,14 @@ release-prepare:
release-prepare-latest: release-prepare
@grep '$(CDIST_CHANGELOG_VERSION)' "$(WEBSITE_MAN_PAGE)" || awk 'BEGIN { print_new = 0; } /All versions/ { print; print_new = 1; next; } print_new == 1 { print; print "* `$(CDIST_CHANGELOG_VERSION) <manual/$(CDIST_CHANGELOG_VERSION)>`_"; print_new = 0; next; } { print; }' "$(WEBSITE_MAN_PAGE)" > "$(WEBSITE_MAN_PAGE)-new" && mv "$(WEBSITE_MAN_PAGE)-new" "$(WEBSITE_MAN_PAGE)" || exit 0
# Build and import documentation from the cdist-contrib project.
sync-contrib:
$(CDIST_CONTRIB_MAKE_HTML)
mkdir -p "$(WEBSITE_MANUALS_DIR)/contrib/"
rsync -va "$(CDIST_CONTRIB_DOCS_HTML_DIST_DIR)/" "$(WEBSITE_MANUALS_DIR)/contrib/"
# Build website.
build:
build: sync-contrib
$(SPHINXH)
@cd "$(WEBSITE_HTML_DIST_DIR)/manual" && rm -f latest && ln -s "$(CDIST_CHANGELOG_VERSION)" latest
@ -76,4 +87,5 @@ release-publish-no-latest: release-no-latest publish
clean:
$(CDIST_CLEAN_HTML)
$(CDIST_CONTRIB_CLEAN_HTML)
$(SPHINXC)

5
src/_static/custom.css
View File

@ -70,3 +70,8 @@ div.documentwrapper {
font-size: 12px;
}
}
/* Remove unwanted space between blocks. */
div.section::after {
display: inline !important;
}

17
src/cdist-changelog.rst
View File

@ -1,6 +1,23 @@
Changelog
---------
next:
* Explorer machine_type: Rewrite (Dennis Camera)
* New type: __sed (Ander Punnar)
* New type: __haproxy_dualstack (Evilham and ungleich)
* Type __apt_update_index: Fix complaint about suite change (Matthias Stecher)
* Type __package_update_index: Fix complaint about suite change (Matthias Stecher)
* Type __package_upgrade_all: Add new --apt-with-new-pkgs argument (Evilham)
* Type __apt_source: Fix complaint about suite change (Matthias Stecher)
* Type __package_apt: Fix complaint about suite change (Matthias Stecher)
* Type __debconf_set_selections: Fix bug where --file was unsupported (Evilham)
* Types __letsencrypt_cert, __grafana_dashboard: Improve bullseye support (Evilham)
* Type __ssh_authorized_key: Also remove tmpfile if removing line (Mark Verboom)
* Type __apt_pin: Add default priority, add comment in generated files (Daniel Fancsali)
* Type __file: make file uploading and attribute changes more atomic (Steven Armstrong)
* Type __dot_file: Add support for using --file parameter (Stephan Leemburg)
* Type __apt_ppa: Replace custom "remove-apt-repository" with add-apt-repository -r (Romain Dartigues)
6.9.8: 2021-08-24
~~~~~~~~~~~~~~~~~
* Type __rsync: Rewrite (Ander Punnar)

35
src/cdist-documentation.rst
View File

@ -1,11 +1,32 @@
Documentation
=============
.. toctree::
:maxdepth: 1
Manuals
~~~~~~~
cdist-manual
cdist contrib types <https://contrib.cdi.st>
cdist-os
cdist-speeches
cdist-changelog
* You will find an **introduction** as well as a **full reference** in the `latest
cdist manual <manual/latest>`_.
* The community-maintained **'contrib' types** are documented on `their own
manual <manual/contrib>`_.
* Experimental features from the **beta** branch (i.e. cdist **trigger**,
**preos** and **scan**) are documented under the `beta manual
<manual/beta>`_.
* Depending how you installed cdist, type manuals might also be availale via
the ``man`` command (e.g. ``man 7 cdist-type__file``).
* Manual for previous releases can be found on the `manual archives page
<cdist-manual-archives.html>`_.
Changelog
~~~~~~~~~
You will find the full changelog `here <cdist-changelog.html>`_.
Talks
~~~~~
* `2013-11-22_eth_linux_erfa <speeches/2013-11-22_eth_linux_erfa.pdf>`_
* `2014-05-08_linuxtag_berlin <speeches/2014-05-08_linuxtag_berlin.pdf>`_
* `2014-05-19_cdi.st-zkb_linux_erfa <speeches/2014-05-19_cdi.st-zkb_linux_erfa.pdf>`_
* `2014-06-10_openclouddays_teaser <speeches/2014-06-10_openclouddays_teaser.pdf>`_
* `2014-11-07_sfs_linux_erfa_cdist_web_prototype <speeches/2014-11-07_sfs_linux_erfa_cdist_web_prototype.pdf>`_
* `2014-11-07_sfs_linux_erfa_cdist4 <speeches/2014-11-07_sfs_linux_erfa_cdist4.pdf>`_

2
src/cdist-features.rst
View File

@ -1,7 +1,7 @@
Features
========
But cdist ticks differently, here is the feature set that makes it unique.
Here are the features that make cdist unique.
**Simplicity**
There is only one type to extend cdist called **type**

167
src/cdist-install.rst
View File

@ -1,167 +0,0 @@
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.5
* 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, as usual, you execute the following command:
.. code-block:: sh
python setup.py install
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>`_.

9
src/cdist-manual.rst → src/cdist-manual-archives.rst
View File

@ -1,10 +1,5 @@
cdist manual
============
* `Latest manual <manual/latest>`_
* Checking out **beta** branch, i.e. cdist **trigger** and **preos** functionality?
Find the manual `here <manual/beta>`_.
cdist manual archives
=====================
**All versions**

19
src/cdist-os.rst
View File

@ -1,19 +0,0 @@
Supported operating systems
===========================
cdist was tested or is know to run on at least
* `Alpine Linux <https://alpinelinux.org>`_
* `Archlinux <http://www.archlinux.org>`_
* `CentOS <http://www.centos.org>`_
* `Debian <http://www.debian.org>`_
* `Devuan <https://devuan.org>`_
* `Fedora <http://fedoraproject.org>`_
* `FreeBSD <http://www.freebsd.org>`_
* `Gentoo <http://www.gentoo.org>`_
* `Mac OS X <http://www.apple.com/macosx>`_
* `NetBSD <https://www.netbsd.org>`_
* `OpenBSD <http://www.openbsd.org>`_
* `Redhat <http://www.redhat.com>`_
* `Ubuntu <http://www.ubuntu.com>`_
* `XenServer <http://www.citrix.com/xenserver>`_

9
src/cdist-speeches.rst
View File

@ -1,9 +0,0 @@
Speeches
========
* `2013-11-22_eth_linux_erfa <speeches/2013-11-22_eth_linux_erfa.pdf>`_
* `2014-05-08_linuxtag_berlin <speeches/2014-05-08_linuxtag_berlin.pdf>`_
* `2014-05-19_cdi.st-zkb_linux_erfa <speeches/2014-05-19_cdi.st-zkb_linux_erfa.pdf>`_
* `2014-06-10_openclouddays_teaser <speeches/2014-06-10_openclouddays_teaser.pdf>`_
* `2014-11-07_sfs_linux_erfa_cdist_web_prototype <speeches/2014-11-07_sfs_linux_erfa_cdist_web_prototype.pdf>`_
* `2014-11-07_sfs_linux_erfa_cdist4 <speeches/2014-11-07_sfs_linux_erfa_cdist4.pdf>`_

31
src/cdist-support.rst
View File

@ -1,31 +0,0 @@
Support
-------
Chat
~~~~
Matrix: ``#cdist:ungleich.ch``
IRC: ``#cdist`` @ `libera <https://libera.chat>`_
Matrix and IRC are bridged.
Mailing list
~~~~~~~~~~~~
Bug reports, questions, patches, etc. should be send to the
`cdist mailing list <https://groups.google.com/forum/#!forum/cdist-configuration-management>`_.
Linkedin
~~~~~~~~
If you have an account
at `Linked in <http://www.linkedin.com/>`_,
you can join the
`cdist group <http://www.linkedin.com/groups/cdist-configuration-management-3952797>`_.
Commercial support
~~~~~~~~~~~~~~~~~~
You can request commercial support for cdist from
`ungleich <http://www.ungleich.ch/>`_.

188
src/cdist-upgrade.rst
View File

@ -1,188 +0,0 @@
How to upgrade cdist
====================
Update the git installation
---------------------------
To upgrade cdist in the current branch use
.. code-block:: sh
git pull
# Also update the manpages
make man
export MANPATH=$MANPATH:$(pwd -P)/doc/man
If you stay on a version branche (i.e. 1.0, 1.1., ...), nothing should break.
The master branch on the other hand is the development branch and may not be
working, break your setup or eat the tree in your garden.
Safely upgrading to new versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To upgrade to **any** further cdist version, you can take the
following procedure to do a safe upgrade:
.. code-block:: sh
# Create new branch to try out the update
git checkout -b upgrade_cdist
# Get latest cdist version in git database
git fetch -v
# see what will happen on merge - replace
# master with the branch you plan to merge
git diff upgrade_cdist..origin/master
# Merge the new version
git merge origin/master
Now you can ensure all custom types work with the new version.
Assume that you need to go back to an older version during
the migration/update, you can do so as follows:
.. code-block:: sh
# commit changes
git commit -m ...
# go back to original branch
git checkout master
After that, you can go back and continue the upgrade:
.. code-block:: sh
# git checkout upgrade_cdist
Update the python package
-------------------------
To upgrade to the lastet version do
.. code-block:: sh
pip install --upgrade cdist
General update instructions
---------------------------
Updating from 3.0 to 3.1
~~~~~~~~~~~~~~~~~~~~~~~~
The type **\_\_ssh_authorized_keys** now also manages existing keys,
not only the ones added by cdist.
Updating from 2.3 to 3.0
~~~~~~~~~~~~~~~~~~~~~~~~
The **changed** attribute of objects has been removed.
Use `messaging </software/cdist/man/3.0.0/man7/cdist-messaging.html>`_ instead.
Updating from 2.2 to 2.3
~~~~~~~~~~~~~~~~~~~~~~~~
No incompatibilities.
Updating from 2.1 to 2.2
~~~~~~~~~~~~~~~~~~~~~~~~
Starting with 2.2, the syntax for requiring a singleton type changed:
Old format:
.. code-block:: sh
require="__singleton_type/singleton" ...
New format:
.. code-block:: sh
require="__singleton_type" ...
Internally the "singleton" object id was dropped to make life more easy.
You can probably fix your configuration by running the following code
snippet (currently untested, please report back if it works for you):
.. code-block:: sh
find ~/.cdist/* -type f -exec sed -i 's,/singleton,,' {} \;
Updating from 2.0 to 2.1
~~~~~~~~~~~~~~~~~~~~~~~~
Have a look at the update guide for [[2.0 to 2.1|2.0-to-2.1]].
* Type **\_\_package* and \_\_process** use --state **present** or **absent**.
The states **removed/installed** and **stopped/running** have been removed.
Support for the new states is already present in 2.0.
* Type **\_\_directory**: Parameter --parents and --recursive are now boolean
The old "yes/no" values need to be removed.
* Type **\_\_rvm_ruby**: Parameter --default is now boolean
The old "yes/no" values need to be removed.
* Type **\_\_rvm_gemset**: Parameter --default is now boolean
The old "yes/no" values need to be removed.
* Type **\_\_addifnosuchline** and **\_\_removeline** have been replaced by **\_\_line**
* The **conf** directory is now located at **cdist/conf**.
You need to migrate your types, explorers and manifests
manually to the new location.
* Replace the variable **\_\_self** by **\_\_object_name**
Support for the variable **\_\_object_name** is already present in 2.0.
* The types **\_\_autofs**, **\_\_autofs_map** and **\_\_autofs_reload** have been removed
(no maintainer, no users)
* Type **\_\_user**: Parameter --groups removed (use the new \_\_user_groups type)
* Type **\_\_ssh_authorized_key** has been replaced by more flexible type
**\_\_ssh_authorized_keys**
Updating from 1.7 to 2.0
~~~~~~~~~~~~~~~~~~~~~~~~
* Ensure python (>= 3.2) is installed on the source host
* Use "cdist config host" instead of "cdist-deploy-to host"
* Use "cdist config -p host1 host2" instead of "cdist-mass-deploy"
* Use "cdist banner" for fun
* Use **\_\_object_name** instead of **\_\_self** in manifests
Updating from 1.6 to 1.7
~~~~~~~~~~~~~~~~~~~~~~~~
* If you used the global explorer **hardware_type**, you need to change
your code to use **machine** instead.
Updating from 1.5 to 1.6
~~~~~~~~~~~~~~~~~~~~~~~~
* If you used **\_\_package_apt --preseed**, you need to use the new
type **\_\_debconf_set_selections** instead.
* The **\_\_package** types accepted either --state deinstalled or
--state uninstaaled. Starting with 1.6, it was made consistently
to --state removed.
Updating from 1.3 to 1.5
~~~~~~~~~~~~~~~~~~~~~~~~
No incompatibilities.
Updating from 1.2 to 1.3
~~~~~~~~~~~~~~~~~~~~~~~~
Rename **gencode** of every type to **gencode-remote**.
Updating from 1.1 to 1.2
~~~~~~~~~~~~~~~~~~~~~~~~
No incompatibilities.
Updating from 1.0 to 1.1
~~~~~~~~~~~~~~~~~~~~~~~~
In 1.1 the type **\_\_file** was split into **\_\_directory**, **\_\_file** and
**\_\_link**. The parameter **--type** was removed from **\_\_file**. Thus you
need to replace **\_\_file** calls in your manifests:
* Remove --type from all \_\_file calls
* If type was symlink, use \_\_link and --type symbolic
* If type was directory, use \_\_directory

10
src/cdist-why.rst
View File

@ -21,11 +21,11 @@ Not only is shell scripting widely known by system engineers,
but it is also a very powerful language. Here are some features
which make daily work easy:
* Configuration can react dynamicly on explored values
* High level string manipulation (using sed, awk, grep)
* Conditional support (**if, case**)
* Loop support (**for, while**)
* Support for dependencies between cdist types
* Configuration can react dynamicly on explored values
* High level string manipulation (using sed, awk, grep)
* Conditional support (**if, case**)
* Loop support (**for, while**)
* Support for dependencies between cdist types
More than shell scripting
-------------------------

8
src/conf.py
View File

@ -47,7 +47,7 @@ master_doc = 'index'
# General information about the project.
project = 'cdist'
copyright = 'ungleich GmbH 2021'
copyright = 'ungleich GmbH 2022'
# author = 'Darko Poljak'
# The version info for the project you're documenting, acts as replacement for
@ -120,8 +120,8 @@ html_theme_options = {
'description': 'usable configuration management',
'github_button': 'false',
'extra_nav_links': {
'Source code repository': 'https://code.ungleich.ch/ungleich-public/cdist',
'ungleich Home': 'https://ungleich.ch',
'source code repository': 'https://code.ungleich.ch/ungleich-public/cdist/',
'ungleich homepage': 'https://ungleich.ch',
},
'show_powered_by': 'false',
'sidebar_width' : '300px',
@ -175,7 +175,7 @@ html_sidebars = {
'navigation.html',
'relations.html',
'searchbox.html',
'donate.html',
'donate.html'
]
}

36
src/index.rst
View File

@ -1,12 +1,35 @@
cdist - usable configuration management
=======================================
cdist is a usable configuration management system.
It adheres to the KISS principle and
is being used in small up to enterprise grade environments.
It natively supports IPv6 since the first release.
cdist is an alternative to other configuration management systems.
cdist is a mature configuration management system that adheres to the KISS
principle. It has been used in small up to enterprise grade environment for
years and effectively is an alternative to other configuration management
system such as `Ansible <https://www.ansible.com/>`_, `Chef
<https://www.chef.io/products/chef-infra>`_ or `Puppet <https://puppet.com/>`_.
Community
~~~~~~~~~
You are welcome to drop by and ask questions on the `#cdist:ungleich.ch
<https://matrix.to/#/#cdist:ungleich.ch>`_ matrix room or ``#cdist`` IRC
channel on `libera <https://libera.chat>`_. The Matrix room and IRC channel
are bridged via a simple relay bot.
Development
~~~~~~~~~~~
Source code repositories and issue trackers can be found on ungleich's software
forge:
* `ungleich-public/cdist <https://code.ungleich.ch/ungleich-public/cdist/>`_: core cdist logic and types.
* `ungleich-public/cdist-contrib <https://code.ungleich.ch/ungleich-public/cdist-contrib/>`_: extra useful types not released as part of core cdist.
* `ungleich-public/cdist-web <https://code.ungleich.ch/ungleich-public/cdist-web/>`_: sources of this website.
Commercial support
~~~~~~~~~~~~~~~~~~
You can request commercial support for cdist from
`ungleich <http://www.ungleich.ch/>`_.
.. toctree::
:maxdepth: 3
@ -16,6 +39,3 @@ cdist is an alternative to other configuration management systems.
cdist-why
cdist-features
cdist-documentation
cdist-install
cdist-upgrade
cdist-support