From 25115a6fae6521bb4f70a1726a3d2eb65b909372 Mon Sep 17 00:00:00 2001
From: viveksantayana <me@viveksantayana.co.uk>
Date: Fri, 17 Jun 2022 02:01:06 +0100
Subject: [PATCH] Wrote installation instructions in the Readme

---
 README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 115 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index e5e976b..4d001de 100644
--- a/README.md
+++ b/README.md
@@ -14,27 +14,131 @@ The clien is designed to work on a server.
 
 ### Pre-Requisites
 
-Server
-Docker
-Docker-Compose
-Git
+- A Debian- or Ubuntu-based server, preferably the latest distribution.
+- Docker (specifically, Docker Engine)
+- Docker-Compose
+- Git
 
 ### Installation
 
+#### Install all the pre-requisites
+
+The first step is to ensure all the prerequisites are available on the server.
+
+To set up the server, consult some of the comprehensive guides on various hosting platforms like Linode or DigitalOcean.
+Here is a [good starting point on setting up a server](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-22-04).
+
+To install Docker and Docker-Compose, consult the respective documentation:
+  - [Install on Ubuntu](https://docs.docker.com/engine/install/ubuntu/) or [Install on Debian](https://docs.docker.com/engine/install/debian/)
+  - [Install Docker-Compose](https://github.com/docker/compose) as per these instructions.
+
+Check if Git is installed on your server using the `git --version` command.
+If it isn't installed, install it.
+This should normally come pre-packaged with your OS distribution.
+But if it doesn't, look up how to for whatever OS you use.
+If you are using Ubuntu or Debian, it should be as easy as using the command:
+
+```$ sudo apt-get install git -y```
+
 #### Preliminary Set-Up: Clone repos and Configure Values
 
-#### Set Up Web Server
+Open a terminal and navigate to the folder where you want to install this app.
+I would suggest using a subfolder within your Home folder:
 
-#### Incorporate SSL
+```$ cd ~ && mkdir ska-referee-test && cd ska-referee-test```
 
-#### Set Up Auto-Renew
+That way, you will ensure you can read and write all the necessary files during installation.
+Once in the destination folder, clone all the relevant files you will need for the installation:
 
-### Alterations
+```$ git clone https://git.vsnt.uk/viveksantayana/ska-referee-test.git .```
 
-## Use
+(Remember to include the trailing dot at the end, as that indicates to Git to download the files in the current directory.)
 
-## Compatibility
+#### Populate Environment Variables
 
-### iOS Limitations
+Configuration values for the app are stored in the environment variables file.
+To set it up, make a copy of the example file and populate it with appropriate values.
+
+```$ cp .env.example .env```
+
+Make sure to use complex, secure strings for passwords.
+Also make sure that the various entries for usernames and passwords match.
+
+#### Input Specific Values for Your Installation
+
+There are some values in the following three files you will need to configure to reflect the domain you are installing this app.
+
+```
+# .env
+
+SERVER_NAME= # URL where this will be hosted.
+```
+
+```
+# install-script.sh
+
+domains=(example.org www.example.org)
+email="" # Adding a valid address is strongly recommended
+```
+
+And four locations in the following file, two for the regular version of the domain and two for the www version:
+
+```
+# nginx/conf.d/ref-test-app.conf
+
+server {
+    server_name domain_name;
+    listen 80 default_server;
+    ...
+}
+
+server {
+    server_name domain_name;
+    listen 443 ssl http2 default_server;
+    ...
+}
+
+server {
+    server_name www.domain_name;
+    listen 80;
+    ...
+}
+
+server {
+    server_name www.domain_name;
+    listen 443 ssl http2;
+    ...
+}
+```
+
+#### Installing SSL Certificates
+
+The app will use SSL certificates to operate through a secure, `https` connection.
+This will be set up automatically.
+However, there is a specific chicken-and-egg problem as the web server, Nginx, won't run without certificates, Certbot, the certificate generator, won't run without the web server.
+So to solve this, there is an automation script we can run that will set up a dummy certificate and then issue the appropriate certificates for us.
+
+```
+$ chmod +x install-script.sh
+$ sudo ./install-script.sh
+```
+
+When we later run the server, Certbot will check for renewals of the SSL certificates every 12 hours, and Nginx will reload the configurations every 6 hours, to make sure everything runs smoothly and stays live.
+
+#### Run the Stack
+
+Everything should be good to run on autopilot at this point.
+Navigate to the root folder of the app, the folder where you have `install-script.sh` and `docker-compose.yml`.
+Run the following command:
+
+```sudo docker-compose up -d```
+
+And you should have the stack running.
+You can register in the app and begin using it.
 
 ### Fonts
+
+The app uses [OpenDyslexic](https://opendyslexic.org/), which is available on-line.
+It also has the option of rendering in other system fonts, but this can vary depending on your operating system.
+Because these are proprietary fonts, they cannot be made available on-line in the same way as open source ones should your system not have them.
+Some fonts may not display correctly as a result.