Where to add example configuration snippits?

[Robin Schneider]

Good evening

I am using a lot of DebOps roles lately and have created some configuration snippets which I think could also come in handy for others. Is there a good place to add them somewhere.

Example. Using the debops.apt_preferences role, I configured apt preferences for my systems to handle various sources in the sources.list:

apt_preferences_list:
  - package: '*'
    suffix: '_Debian'
    raw: |
      Explanation: Configure the installed release higher as the default (500) so that those packages are preferred.
      Package: *
      Pin: release o=Debian,n={{ ansible_distribution_release }}
      Pin-Priority: 600

      Explanation: The default priority of packages from backports is 100 which is even lower then testing and unstable (500).
      Explanation: Prefer backports over testing and unstable but don’t automatically upgrade to it.
      Package: *
      Pin: release o=Debian Backports,n={{ ansible_distribution_release }}-backports
      Pin-Priority: 400

      Explanation: Install packages from testing if no package with the same name is available in release archives or backports or other archives.
      Package: *
      Pin: release o=Debian,a=testing
      Pin-Priority: 300

      Explanation: Only install packages from unstable if explicitly asked for or the package is pined.
      Package: *
      Pin: release o=Debian,a=unstable
      Pin-Priority: -1

      Explanation: Only install packages from experimental if explicitly asked for or the package is pined.
      Package: *
      Pin: release o=Debian,a=experimental
      Pin-Priority: -1

I also worked a bit on ownCloud tuning. I would propose to add an directory to each role for example configurations which might be useful for that role. What do you think?

[Maciej Delmanowski]

Right now documentation is stored in role repositories, in docs/ directory, as .rst files. They are then aggregated by https://github.com/debops/docs repository on http://docs.debops.org/.

You could probably convert debops.apt_preferences role to new documentation format (many examples available), at least before I get to it, and put your guides in the docs, similar to http://docs.debops.org/en/latest/ansible/roles/ansible-stunnel/docs/guides.html

This system keeps roles and their documentation neatly packaged together, especially that yaml2rst script lets me scrape role defaults file and have up to date variable documentation, however it probably is hard to modify, epseically that I need to update docs.debops.org repository via submodules.

Do you think that a normal wiki would be better? I would like to keep the scraping aspect somehow, and .rst format is basically native now, so DokuWiki would be hard. I wonder what alternatives are there, if any. Right now, I would suggest keeping docs with the roles themselves.

[Robin Schneider]

Looks good to me. I also like the idea of having individual roles and there documentation packaged together in a git repo. I think that is the best option. It also allows a better review process of changes then with using DokuWiki I think and is more "standalone" (I could render the documentation locally via Sphinx) and distributed.

Git submodules can be tricky, but when used correctly, they allow good control over what has changed.

I will look into this the next days later 😄.