From 62d5a3cccab5f16c486aa092d8a039e75c5ee609 Mon Sep 17 00:00:00 2001
From: Sam Al-Sapti <sam@sapti.me>
Date: Fri, 25 Nov 2022 23:31:30 +0100
Subject: [PATCH] Add README.md

---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..bafd8c3a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+# data.coop infrastructure
+
+This repository contains the code used to deploy data.coop's services
+and websites. We use Ansible to encode our infrastructure setup. Only
+the association's administrators have access to deploy the services.
+
+## Deploying
+
+To deploy the services, the included `deploy.sh` script can be used. The
+Ansible playbook uses two custom-made roles (in the `roles/` directory).
+The script has options to deploy only one of the roles, which are namely
+`ubuntu_base` and `docker`, the latter of which is for deploying the
+services themselves using Docker containers. Select services only can
+also be specified. By default, the script deploys everything.
+
+Here is a summary of the options that can be used:
+
+```console
+$ ./deploy.sh                   # deploy everything
+$ ./deploy.sh base              # deploy the ubuntu_base role only
+$ ./deploy.sh services          # deploy the docker role only
+$ ./deploy.sh services SERVICE  # deploy SERVICE only
+```
+
+`SERVICE` should match one of the filenames in
+`roles/docker/tasks/services/`, but without the `.yml` extension
+
+## Testing
+
+In order for us to be able to test our setup locally, we use Vagrant to
+deploy the services in a virtual machine. To do this, Vagrant and
+VirtualBox must both be installed on the development machine. Then, the
+services can be deployed locally by using the `vagrant` command-line
+tool. The working directory needs to be the root of the repository for
+this to work properly.
+
+> Note: As our secrets are contained in an Ansible Vault file, only the
+> administrators have the ability to run the deployment in Vagrant.
+> However, one could replace the vault file for testing purposes.
+
+Here is a summary of the commands that are available with the `vagrant`
+command-line tool:
+
+```console
+$ vagrant up         # Create and provision the VM
+$ vagrant provision  # Re-provision the VM
+$ vagrant ssh        # SSH into the VM
+$ vagrant halt       # Power down the VM
+$ vagrant destroy    # Power down and delete the VM
+```
+