From e74553a5c1bcf2d6da7643d7efaa6180a772ebc2 Mon Sep 17 00:00:00 2001
From: Caila Finn <caila.finn@stfc.ac.uk>
Date: Wed, 25 Sep 2024 16:57:01 +0100
Subject: [PATCH] Add a readme as documentation

RE #99
---
 Linux/external-data-mirror/ansible/readme.md | 56 ++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 Linux/external-data-mirror/ansible/readme.md

diff --git a/Linux/external-data-mirror/ansible/readme.md b/Linux/external-data-mirror/ansible/readme.md
new file mode 100644
index 0000000..c5d7169
--- /dev/null
+++ b/Linux/external-data-mirror/ansible/readme.md
@@ -0,0 +1,56 @@
+# External Data Mirror Deployment
+
+This allows for additional copies of the external data to be generated to reduce the load
+on the main server. 
+
+Developers deploying these playbooks will require ssh access to `mantidproject.org`.
+
+## Setup
+
+- Provision a new linux virtual machine (VM) (on OpenStack at STFC) with an ssh key that 
+  you have on your system.
+- Create an `ansible` conda environment:
+
+```sh
+mamba create -n ansible ansible
+mamba activate ansible
+```
+
+- Install 3rd party ansible packages from `ansible-galaxy`:
+
+```sh
+ansible-galaxy install -r requirements.yml
+```
+
+- Create an `inventory.txt` file in the following format:
+
+    - `VM_IP_ADDRESS`: IP address of the node you just provisioned. 
+    - `IP_TO_COPY_FROM`: IP address or domain (usually `mantidproject.org`) that holds 
+      the external data you want to copy.
+    - `DIR_NAME`: The directory in the `/srv/` directory on the server that holds the 
+      rest of the path to the external data. On `mantidproject.org` this is formatted 
+      as the main server's IP.
+
+```ini
+[all]
+<VM_IP_ADDRESS> main_server_hostname=<IP_TO_COPY_FROM> main_data_srv_dir=<DIR_NAME>
+```
+
+## Deployment
+
+- Deploy the playbook to the list of machines in the inventory.
+
+```sh
+ansible-playbook -i inventory.txt external-data-mirror.yml -u <YOUR_VM_USERNAME> -K
+```
+
+- There are 3 tags for the different parts of the deployment:
+
+  - `setup`: Sets up the VM with ssh keys for the whole DevOps team and a docker 
+    installation.
+  - `mirror`: Creates a copy of the data on the new VM and sets up a crontab job to keep 
+    it in sync with any new data added on the main server.
+  - `server`: Spins up a docker container to host the server with a mounted volume
+    containing the copied data.
+
+The new server can now be accessed by: `http://<VM_IP_ADDRESS>/external-data/MD5/<TEST_FILE_HASH>`
\ No newline at end of file