Commit 7841c6ef authored by Maciej Delmanowski's avatar Maciej Delmanowski

More updates in the project documentation

Use better fonts for PDF documentation generated on the ReadTheDocs
website.

Use 'git describe' command to indicate the version of the documentation,
based on the closest tag in the repository.
parent 6df43e3a
# -*- coding: utf-8 -*-
#
# DebOps documentation build configuration file
# Copyright (C) 2014-2017 DebOps Project https://debops.org/
# Copyright (C) 2014-2018 DebOps Project https://debops.org/
#
# This file is execfile()d with the current directory set to its
# containing dir.
......@@ -69,10 +69,10 @@ copyright = u'2014-2018, {}'.format(author)
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'master'
# The full version, including alpha/beta/rc tags.
release = 'master'
release = os.popen('git describe').read().strip()
# The short X.Y version.
version = release
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
......@@ -140,7 +140,7 @@ if not on_rtd: # only import and set the theme if we're building docs locally
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_theme_options = {
'collapse_navigation': True,
'logo_only': True
'logo_only': False
}
except Exception:
pass
......@@ -228,13 +228,17 @@ htmlhelp_basename = 'DebOpsdoc'
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
'papersize': 'a4paper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
'pointsize': '11pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
'preamble': r'''
\usepackage{charter}
\usepackage[defaultsans]{lato}
\usepackage{inconsolata}
''',
}
# Grouping the document tree into LaTeX files. List of tuples
......@@ -247,7 +251,7 @@ latex_documents = [
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
latex_logo = '_static/images/debops-small.png'
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
......@@ -309,7 +313,7 @@ texinfo_documents = [
epub_title = u'DebOps'
epub_author = author
epub_publisher = author
epub_copyright = u'2014-2017, Maciej Delmanowski'
epub_copyright = u'2014-2018, Maciej Delmanowski'
# The basename for the epub file. It defaults to the project name.
# epub_basename = u'DebOps'
......
......@@ -40,6 +40,8 @@ question can be physical or virtual machines, or even LXC/Docker containers.
introduction/community
introduction/philosophy
introduction/timeline
introduction/other-projects
introduction/references
.. toctree::
:caption: News
......
Community
=========
Description of DebOps community.
DebOps has a small but active community of developers and users. Come on in and
say hi!
DebOps monorepo
---------------
Main development of the project is done in its :command:`git` monorepo, using
a distributed development model. The default location of the monorepo is the
`DebOps GitHub repository`__, used for the issues and pull requests. There's
also a `read-only mirror on GitLab`__ used to manage the public test pipeline
based on `GitLab CI`__.
The developers and users maintain their own `monorepo forks`__ on GitHub, used
for development and pull requests.
.. __: https://github.com/debops/debops/
.. __: https://gitlab.com/debops/debops/
.. __: https://about.gitlab.com/features/gitlab-ci-cd/
.. __: https://github.com/debops/debops/network/members
IRC channel
-----------
The official ``#debops`` IRC channel is located on the `FreeNode`__ IRC
network. You can use it to chat in real time about DebOps, get help with any
pressing issues and compare notes with other DebOps users.
.. __: https://freenode.net/
Mailing list
------------
The DebOps project has `its own mailing list`__, ``debops-users``, based on
Mailman. The list has low traffic and is used for notifications about
significant changes in the project, and more asynchronous communication. You
can also check out the `mailing list archives`__.
.. __: https://lists.debops.org/mailman/listinfo/debops-users
.. __: https://lists.debops.org/pipermail/debops-users/
Other projects
==============
There are third-party projects that might be interesting for DebOps users,
either as source of inspiration or as an alternative configuration management
frameworks.
Third-party projects based on DebOps
------------------------------------
DebOps is very suitable to usage as a base for other IT infrastructure projects
based on Ansible. Here you can find some of them, that are available publicly.
`Drupsible`__
~~~~~~~~~~~~~
The Drupsible Project, managed by `Mariano Barcia`__, uses DebOps as a
deployment platform for Drupal applications.
.. __: https://www.drupal.org/project/drupsible
.. __: https://www.drupal.org/u/marianobarcia
`DebOps for WordPress`__
~~~~~~~~~~~~~~~~~~~~~~~~
The DebOps for WordPress project, maintained by `Carl Alexander`__, provides a
custom set of playbooks and roles that can be run on top of DebOps to deploy a
secure WordPress site.
.. __: https://github.com/carlalexander/debops-wordpress
.. __: https://carlalexander.ca/
`ypid-ansible-common`__
~~~~~~~~~~~~~~~~~~~~~~~
This is a git repository which bundles all the building blocks of config
management code, managed by `Robin 'ypid' Schneider`__. The building blocks are
included as git submodules. The repository can be thought of an alternative and
more generic (not limited to DebOps roles) form of distributing and updating
config management related assets (Ansible playbooks, roles, inventory presets
and more) in an end-to-end authenticated way. The repo also bundles a script to
review and pull down the latest changes of the git submodules.
.. __: https://github.com/ypid/ypid-ansible-common/
.. __: https://me.ypid.de/
Third-party projects similar to DebOps
--------------------------------------
Other people and teams are developing software projects which are similar to
DebOps either in scope or used software. You might find some of them
interesting, or if you don't want to use DebOps specifically, other projects
here might be more to your liking.
`Sovereign`__
~~~~~~~~~~~~~
Sovereign is a set of Ansible playbooks that you can use to build and maintain
your own personal cloud based entirely on free software. It was one of the
original inspirations to create DebOps.
.. __: https://github.com/sovereign/sovereign
`Streisand`__
~~~~~~~~~~~~~
Streisand uses Ansible to set up a new server running L2TP/IPsec, OpenConnect,
OpenSSH, OpenVPN, Shadowsocks, sslh, Stunnel, a Tor bridge, and WireGuard. It
also generates custom instructions for all of these services. At the end of the
run you are given an HTML file with instructions that can be shared with
friends, family members, and fellow activists.
.. __: https://github.com/StreisandEffect/streisand
`ansible-lanparty`__
~~~~~~~~~~~~~~~~~~~~
Collection of integrated Ansible roles used to run LAN events. This repository
consists of roles that are purpose-built, lean and as easy as possible to
understand and modify. The roles are built to simplify and accelerate, not to
obscure.
.. __: https://github.com/ti-mo/ansible-lanparty
`FOSDEM Infrastructure`__
~~~~~~~~~~~~~~~~~~~~~~~~~
This repository contains a set of Ansible playbooks used to manage the video
recording infrastructure used at the `FOSDEM`__ conference.
.. __: https://github.com/FOSDEM/infrastructure
.. __: https://fosdem.org/
`LEAP Platform`__
~~~~~~~~~~~~~~~~~
The LEAP Platform is set of complementary packages and Puppet server recipes to
automate the maintenance of LEAP services in a hardened Debian environment. Its
goal is to make it as painless as possible for sysadmins to deploy and maintain
a service provider's infrastructure for secure communication. These recipes
define an abstract service provider. It is a set of Puppet modules designed to
work together to provide to sysadmins everything they need to manage a service
provider infrastructure that provides secure communication services.
.. __: https://github.com/leapcode/leap_platform
`System Integrity Management Platform`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The System Integrity Management Platform (SIMP) is a Puppet-based framework
designed around the concept that individuals and organizations should not need
to repeat the work of automating the basic components of their operating system
infrastructure.
.. __: https://github.com/NationalSecurityAgency/SIMP
Quick Start
===========
You can try out DebOps without installing it on your host, using a Docker
container or a Vagrant virtual machine. The DebOps playbook can be executed
against the container/VM to configure it, or the container/VM can be used as
Ansible Controller to configure other, remote hosts.
You can try out DebOps without installing it on your computer, by using
a Docker container or a Vagrant virtual machine to execute Ansible commands.
Start the Ansible Controller host
---------------------------------
DebOps uses the concept of an "Ansible Controller", a central management host
where Ansible playbooks are executed in a "push" mode against other hosts.
Normally DebOps would be installed on that host either manually or through
a package manager, however you can set one up using either a Docker container
or a Vagrant virtual machine and execute Ansible commands from there.
The Ansible Controller can also be managed by DebOps as long, as it's based on
a compatible operating system, ie. Debian or Ubuntu. A suitable configuration
to do so will be automatically generated for you in the
:file:`~/src/controller/` directory located on the container/VM.
.. warning::
The default configuration assumes that this is a testing environment - for
example, `Diffie-Hellman parameters`__ generated by the :ref:`debops.dhparam` role
are very small, only 512 bytes, to make their generation faster. If you want to
use the configuration located in :file:`~/src/controller/` directory against
production hosts, you should review it before doing so.
.. __: https://security.stackexchange.com/questions/94390/
.. _quick_start__docker:
Quick start with Docker
-----------------------
~~~~~~~~~~~~~~~~~~~~~~~
Start a Docker container which acts as an Ansible Controller host with DebOps
support, based on Debian Stretch:
......@@ -29,7 +51,7 @@ image configuration.
.. _quick_start__vagrant:
Quick start with Vagrant
------------------------
~~~~~~~~~~~~~~~~~~~~~~~~
Start a Vagrant VM which acts as an Ansible Controller host with DebOps
support, based on Debian Stretch:
......@@ -42,24 +64,31 @@ support, based on Debian Stretch:
The configuration relies heavily on your Vagrant environment. Having a real
domain is benefical. The box can be used to manage other Debian hosts as well.
Vagrant will include contents of the cloned DebOps repository in the
:file:`/vagrant/` directory on the created VM. This can be useful for project
development.
See the `DebOps Vagrantfile`__ for more details and configuration variables.
.. __: https://github.com/debops/debops/blob/master/Vagrantfile
Execute DebOps playbook against the host
Run the DebOps playbook against the host
----------------------------------------
When your desired container/VM is up and ready, you can find the prepared
DebOps project configuration in the :file:`src/controller/` subdirectory of the
DebOps project configuration in the :file:`~/src/controller/` subdirectory of the
unprivileged user account. To run DebOps playbook against the host, execute the
commands:
.. code-block:: console
cd src/controller
cd ~/src/controller
debops
Docker notes
~~~~~~~~~~~~
At the moment, some of the DebOps roles don't work well in a Docker container,
therefore inside one you might want to skip some roles for now:
......@@ -67,10 +96,13 @@ therefore inside one you might want to skip some roles for now:
debops --skip-tags role::sysctl
.. warning::
Not everything will work as expected inside a Docker container, for example
various daemons are not restarted properly. However you can still use the
container to manage remote DebOps hosts, and inspect the configuration files
generated when DebOps has been run against the container itself.
The default configuration assumes that this is a testing environment - for
example, Diffie-Hellman parameters generated by the :ref:`debops.dhparam` role
are very small, only 512 bytes, to make their generation faster. If you want to
use the configuration located in :file:`src/controller/` directory against
production hosts, you should review it before doing so.
Some of the remote host state as well as the general environment is managed on
the Ansible Controller itself. If you want to use a Docker container as one,
you might want to enable a persistent storage volume for the project
directories, where :ref:`secrets <debops.secret>`,
:ref:`Certificate Authorities <debops.pki>` and other data are kept safe.
References
==========
The creation of DebOps wouldn't be possible without massive amounts of
documentation, knowledge and know-how present on the Internet. Many solutions
to problems encountered during the development have been found on various
blogs, HOWTOs and other documentation, it would be hard to list them all.
However, there are some notable entries which you can use for reference during
the development of your own IT infrastructure.
`The Debian Administrator's Handbook`__
---------------------------------------
.. __: https://debian-handbook.info/
This is a very accessible book about the Debian Project and Debian OS
administration, written by the project's Developers. Highly recommended for
beginners.
`The Debian Project documentation`__
------------------------------------
.. __: https://www.debian.org/doc/
A reference page with huge amount of documentation sources related to Debian
GNU/Linux operating system.
`ArchWiki`__
------------
.. __: https://wiki.archlinux.org/
The official wiki of the `Arch Linux`__ distribution, maintained by its users.
The operating system itself might be different, however many software packages
are present both in Debian as well as Arch, and solutions found on the wiki are
usually easily applicable to Debian hosts.
.. __: https://archlinux.org/
`Computing Infrastructure Setup Protocols`__
--------------------------------------------
.. __: http://infrastructure.blueprint.org/
Orderly deployment of cost-effective and scalable computing infrastructure for
life-science research groups. Yao M, Luo W, and Hogue C.W.V. (2009) JOURNAL VOL:PP
`Infrastructures.Org`__
-----------------------
.. __: http://www.infrastructures.org/
This is an older website which discusses good practices for IT infrastructure
deployment. The technologies used are ancient from the perspective of the IT
departments today, however the methodology used during the deployment might
still be useful and relevant.
`Larg's Internet Cluster`__
---------------------------
.. __: https://web.archive.org/web/20160613213246/http://www.planetlarg.net:80/
This is a website with description of the build process of an Internet Cluster.
The `original website`__ seems to be gone, however the `Web Archive`__ version is
available.
.. __: http://planetlarg.net/
.. __: https://web.archive.org/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment