Add an introductory chapter to the reference documentation

docs/reference.md

@@ -5,6 +5,62 @@
 
 [[_TOC_]]
 
+# Overview
+
+*Float* is a minimalistic toolkit for managing container-based
+services on "bare-metal" hardware or virtual machines. This type of
+software is often known as a *container orchestration* framework.
+
+Compared with other, more powerful and sophisticated entries in this
+space (Kubernetes, Nomad, etc), *float* attempts to be both much, much
+*simpler* in its underlying concepts and data model, and more
+*featureful*, by providing a set of high quality built-in services
+that offer a lot of the common functionality one would expect in a
+distributed environment.
+
+Float attempts to reduce the complexity of the problem space by making
+many explicit and radical decisions on behalf of the user: while this
+limits its flexibility, we think it manages to strike a good balance
+between expressive power and simplicity. The criteria for trade-offs
+is that, while float might not provide high availability mechanisms by
+itself, it must be possible (and easy) to build highly available
+services on top of it.
+
+The first and most important of such decisions is that float is a
+*static* orchestrator: there is no dynamic allocation of resources, no
+auto-scaling of service instances, no automatic rescheduling of
+instances on broken machines, etc. All changes are actuated manually.
+If this looks like the behavior of a *push-based* configuration
+management system, that's because, although its API is isolated from
+the implementation, float is built on top of one of them: Ansible, and
+it is in fact implemented as a set of Ansible plugins and roles. This
+choice allows for a great deal of extensibility (at the cost of
+coupling with this specific CMS), and lets float take advantage of the
+existing ecosystem of tools and best practices. The lowest layer of
+float's functionality (which could be summarized as "using Ansible to
+run containers") is implemented with common and familiar models, using
+*podman* and *systemd* to run containers: this helps with gradually
+transitioning legacy services to a containerized model, as it's easy
+to make any systemd service into a float service and integrate it with
+the built-in functionality.
+
+Other important simplifications include:
+
+* *1:1 instance/host mapping* - the scheduler won't run more than one
+  instance of a service on each host;
+* *manual port assignments* - you must manually pick a unique port for
+  your services, there's no automatic allocation;
+* the *service discovery protocol* is based on simple DNS hostname
+  lookups - as a consequence, clients are expected to know the port
+  that they need to be talking to.
+
+Float does not make assumptions on the shape of the deployment
+infrastructure, but it wants to self-host its built-in services
+(including HTTP and DNS), so a production deployment will probably
+need at least two separate servers for redundancy. The design of some
+of float built-in services, such as the HTTP routing layer, naturally
+suggests a two-tier architecture, but float will not force you to use
+it.
 
 # Services