On Jul 04, Nicolas Quiniou-Briand wrote:
What I want to do is:
- complete missing informations
- include a section to bootstrap a new host with a dedicated account like
"ansible-admin". Current guide is focused on bootstraping new host with your
local current account.
- show how to manage only some parts of your host with DebOps (for example:
I don't want to manage users)
I would like to get your input on this "plan" and know if you would like to
add other things.
I think that there are four areas the documentation should be focused on,
which correspond to the current outline of the documentation on
- user guide: DebOps installation, usage of the 'debops*' scripts, layout of
the project directory, what's different from normal Ansible usage
- admin guide: documentation focused on the actual environment DebOps is
designed do manage and how can it be used. Suggestions for infrastructure
design (number of hosts, what services where, use of virtualization and
containers, etc.), deployment of specific services like GitLab, separate
section about deploying clustered environment with LDAP and shared services
- developer guide: tips about how to develop the project, a general roadmap,
how the roles should look like, how new roles are added
- tester guide: how to deploy and use a test environment for DebOps, both
Travis-CI tests (what packages are needed, etc.), and GitLab CI + GitLab
I suppose that the Getting Started guide could be used as a "first taste" on
how to deploy one or two services, one simple like DokuWiki, and another more
complex like something with a database. I'm not really sure what are the
pitfalls for the new DebOps users, what is hard to understand and what in
those first steps could be improved.
I'm considering adding a Beginner guide section, which would start by
explaining basics of Debian from the minimal installation to installing
Ansible, next section could compare the steps needed in the previous one to
how that would be done in Ansible so that users can be acclimated to it, and
then move to installation of DebOps and deployment of the 'debops.core' role
to see how DebOps roles and playbooks are used. Would that be interesting to
have, or is that too low level to consider spending time on?
What I want to do after is to cover bootstrap-ldap but in a separate
That could be incorporated into the Admin Guide, in section focused on
In my opinion, something missing when you start to use DebOps are
Documentation contains example but, from my point of view, they are too
generic. I would like to have some examples that covers some uses cases like
"I want to set up GitLab runner hosts with vagrant-libvirt enabled"
Agreed. I can see how it might be hard to connect the dots at first - for this
you would need to run the common playbook, ifupdown, libvirtd and
gitlab_runner, but it might not be obvious. This could also be an article in
the Admin Guide.
My proposal is to have a list of DebOps projects in the DebOps
cover some use cases. Two advantages:
* new users can directly reuse this examples and adapt them to fit their
* we could use these examples as integration tests to test "real" use cases
There is a https://github.com/debops/examples/
repository with a few ready to
go "project directories", but they might not be up to date. Perhaps they could
be moved to the 'lib/examples/' subdirectory in the monorepo, where they
shouldn't interfere with anything important. That way the examples could be
included in the project documentation as well. I'll see how this could be done
afte the next release which I'm aiming for right after Debian Buster.
I'm interested to have a debops-devel list in order to speak about
development of the DebOps project.
Hmm, is a separate list really needed at this point. DebOps development is
probably closely related to its usage, and the debops-users list seems to be
quiet enough at the moment, so that increase in traffic related to the
development shouldn't hurt. Unless you see it for a different content, like
GitHub commit messages and such? Then sure, I could create it.