From 5701d5056215ecd9ac924eb3e208596254338f59 Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Wed, 6 Sep 2023 10:49:09 +0100
Subject: [PATCH] Add README for deployment

---
 README.md            |  6 +++
 deployment/README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++
 src/lib.rs           |  7 ++++
 3 files changed, 101 insertions(+)
 create mode 100644 deployment/README.md

diff --git a/README.md b/README.md
index 7d9793e..f396dc7 100644
--- a/README.md
+++ b/README.md
@@ -129,6 +129,12 @@ In particular, the following are known limitations which we intend to address:
 
 There are various ways to run the Reductionist server.
 
+### Production deployment
+
+Reductionist provides an Ansible playbook to easily deploy it and supporting
+services to one or more hosts. See the [deployment
+README](deployment/README.md) for details.
+
 ### Running in a container
 
 The simplest method is to run it in a container using a pre-built image:
diff --git a/deployment/README.md b/deployment/README.md
new file mode 100644
index 0000000..b79f0c0
--- /dev/null
+++ b/deployment/README.md
@@ -0,0 +1,88 @@
+# Deployment
+
+This directory contains an Ansible playbook to deploy Reductionist and
+supporting services to one or more hosts.
+
+The following OS distributions are supported:
+
+* Ubuntu 20.04-22.04
+* CentOS Stream 8-9
+* Rocky Linux 8-9
+
+The following services are supported:
+
+* Docker engine
+* Step CA Certificate Authority (generates certificates for Reductionist)
+* Step CLI (requests and renews certificates)
+* Minio object store (optional, for testing)
+* Prometheus (monitors Reductionist and HAProxy)
+* Reductionist
+* HAProxy (load balancer for Reductionist)
+
+## Configuration
+
+An example Ansible inventory file is provided in [inventory](inventory) which
+defines all groups and maps localhost to them. For a production deployment it
+is more typical to deploy to one or more remote hosts.
+
+The following example inventory places HAProxy, Prometheus and Step CA on
+`reductionist`, while Reductionist is deployed on `reductionist1` and
+`reductionist2`.
+
+```ini
+[haproxy]
+reductionist1
+
+[prometheus]
+reductionist1
+
+[reductionist]
+reductionist[1:2]
+
+[step:children]
+reductionist
+
+[step-ca]
+reductionist1
+
+[docker:children]
+haproxy
+minio
+prometheus
+reductionist
+step-ca
+```
+
+Some variables are provided to configure the deployment in the
+[group_vars](group_vars) directory. Reductionist configuration options may be
+specified using environment variables.
+
+## Installation
+
+Install Python dependencies:
+```sh
+pip install -r deployment/requirements.txt
+```
+
+Install Ansible collections:
+```sh
+ansible-galaxy collection install -r deployment/requirements.yml
+```
+
+## Deployment
+
+Run the playbook:
+```sh
+ansible-playbook -i deployment/inventory deployment/site.yml
+```
+
+If you want to run only specific plays in the playbook, the following tags are
+supported and may be specified via `--tags <tag1,tag2>`:
+
+* `docker`
+* `step-ca`
+* `step`
+* `minio`
+* `prometheus`
+* `reductionist`
+* `haproxy`
diff --git a/src/lib.rs b/src/lib.rs
index b370fa2..8505319 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -124,6 +124,13 @@
 //!
 //! There are various ways to run the Reductionist server.
 //!
+//! ### Production deployment
+//!
+//! Reductionist provides an Ansible playbook to easily deploy it and supporting
+//! services to one or more hosts. See the [deployment
+//! README](https://github.com/stackhpc/reductionist-rs/blob/main/deployment/README.md) for
+//! details.
+//!
 //! ### Running in a container
 //!
 //! The simplest method is to run it in a container using a pre-built image: