Add a bunch of documentation on running in prod-like envs

README.md

@@ -67,6 +67,7 @@ and in README files for individual Ansible roles:
 
 * [Quick start guide](docs/quickstart.md)
 * [Guide to Ansible integration](docs/ansible.md)
+* [Notes on running in production](docs/running.md)
 * [Configuration reference](docs/configuration.md)
 * [Service discovery protocol](docs/service_mesh.md)
 * [HTTP router](docs/http_router.md)

docs/configuration.md

@@ -451,6 +451,30 @@ attribute.
 *master_election* attribute is also true, the backup job will only be
 run on the master host for the service.
 
+### Volumes
+
+Volumes represent LVs that are associated with a service. They are
+managed by float, which makes sure that they are present on the
+hosts. Volumes aren't currently being ever removed, because we're
+scared of deleting data.
+
+Volumes are listed under the service attribute `volumes`, a list of
+objects with the following attributes:
+
+`name`: Volume name (mandatory).
+
+`path`: Path where it should be mounted (mandatory).
+
+`owner`: Owner of the mountpoint (default: root).
+
+`group`: Group of the mountpoint (default: root).
+
+`mode`: Mountpoint mode (default: 0755).
+
+The LVs are created in the volume specified by the `volumes_vg` global
+configuration variable, which by default is *vg0*. The VG must already
+exist, float will not attempt to create it.
+
 ## Examples
 
 Let's look at some example *services.yml* files:

docs/dependencies.md

@@ -31,6 +31,10 @@ such as *dpkg-buildpackage*.
 * [ai3/thirdparty/rsyslog-exporter](https://git.autistici.org/ai3/thirdparty/rsyslog-exporter)
 * [ai3/thirdparty/restic](https://git.autistici.org/ai3/thirdparty/restic)
 
+These are distributed via our own package repository at
+*deb.autistici.org*, which currently supports the *amd64* and *arm64*
+binary architectures.
+
 ### Docker images
 
 For Docker images it's just a *docker build*.

docs/quickstart.md

@@ -244,7 +244,12 @@ host1*) and examine the state of things there. On testing
 environments, syslog logs are also dumped to files below
 */var/log/remote/*, which might be simpler than using the Kibana UI.
 
-# But it's so slow!
+# Next steps
+
+Read on to [running float in a production environment](running.md),
+and the [configuration reference](configuration.md)!
+
+# Appendix: But it's so slow!
 
 Yes, Ansible is generally pretty slow at doing its thing, for a number
 of reasons (among those the fact that we create a large number of

docs/running.md

+Running *float*
+===
+
+This document collects a number of things to be aware of when running
+*float* in production, or generally on machines with real public IP
+addresses.
+
+## General system setup
+
+Float targets need to have Debian Stretch installed.
+
+Float likes to think it "owns" the machines it's deployed on: it will
+assume it can modify the system-level configuration, install packages,
+start services, etc.
+
+However, it assumes that certain functionality is present, either
+managed manually or with some external mechanism (your own Ansible
+roles, for instance):
+
+* Network configuration must be externally managed, except for the
+  [network overlays](service_mesh#network-overlays) explicitly
+  configured in *float*.
+
+* Partitions, file systems, LVs must be externally managed, with the
+  exception of the volumes explicitly defined in your configuration,
+  which will be created by *float* when necessary. See the [relevant
+  configuration reference](configuration#volumes).
+
+* SSH access and configuration must be externally managed **unless**
+  you explicitly set *enable_ssh=true* (and add SSH keys to your admin
+  users), in which case *float* will take over SSH configuration and
+  you might need to modify your Ansible SSH configuration after the
+  first run. See the [relevant configuration
+  reference](configuration#ssh).
+
+## Choosing a domain
+
+Float assumes it has full control of the DNS zone you configure in the
+*domain* global configuration variable
+([ref.](configuration#global-configuration-variables)). It is best to
+pick a new sub-domain of a zone you control for this purpose, so that
+you can eventually set up a NS record for it and delegate it to the
+*float*-managed frontends.
+
+## Disable testing features
+
+Float runs a lot of testing-only features that are useful for
+debugging but should be disabled in production, or whenever the target
+machines are publicly accessible.
+
+Remember to explicitly set
+
+```yaml
+testing: false
+```
+
+in your configuration, to disable all testing-related features.
+