build: fully update deployment process and provide docs

.gitignore

@@ -21,5 +21,6 @@ deployment-key*
 # Deployment
 /.dbbackup/
 .vagrant/
+/custom
 staging.yml
 production.yml

deploy/README.md

@@ -0,0 +1,54 @@
+# BRECcIA Mapper Deployment
+
+BRECcIA Mapper is intended to be deployed using Ansible and Docker.
+It has been tested on RHEL7 and RHEL8, though with minor modification to the Ansible playbook it is expected to deploy correctly on other Linux variants (e.g. Ubuntu).
+
+## Development Deployment
+
+Prerequisites:
+
+- [Vagrant](https://www.vagrantup.com/)
+- [Ansible](https://www.ansible.com/)
+
+Using Vagrant, we can create a virtual machine and deploy BRECcIA Mapper using the same provisioning scripts as a production deployment.
+To deploy a local development version of BRECcIA Mapper inside a virtual machine, use:
+
+```
+vagrant up
+```
+
+Once this virtual machine has been created, to redeploy use:
+
+```
+vagrant provision
+```
+
+And to stop the virtual machine use:
+
+```
+vagrant halt
+```
+
+For further commands see the [Vagrant documentation](https://www.vagrantup.com/docs/cli).
+
+## Production Deployment
+
+Prerequisites:
+
+- [Ansible](https://www.ansible.com/)
+
+To perform a production deployment of BRECcIA Mapper:
+
+1. Copy the `inventory.example.yml` to `inventory.yml`
+2. Edit this file:
+  - Use your server's hostname instead of `example.com`
+  - Disable debugging
+  - Replace the secret key with some text known only to you
+3. Run the Ansible playbook with this inventory file using:
+
+```
+ansible-playbook playbook.yml -i inventory.yml -K -k -u <SSH username>
+```
+
+This will ask for your SSH and sudo passwords for the server, before deploying.
+To redeploy updates, the same command can be run again - it's safe to redeploy on top of an existing deployment.

deploy/Vagrantfile

@@ -8,13 +8,12 @@
 Vagrant.configure("2") do |config|
   # Every Vagrant development environment requires a box. You can search for
   # boxes at https://vagrantcloud.com/search.
-  config.vm.box = "centos/7"
+  config.vm.box = "generic/rocky8"
 
   # Create a forwarded port mapping which allows access to a specific port
   # within the machine from a port on the host machine and only allow access
   # via 127.0.0.1 to disable public access
-  config.vm.network "forwarded_port", guest: 80, host: 8888, host_ip: "127.0.0.1"
+  config.vm.network "forwarded_port", guest: 80, host: 8080, host_ip: "127.0.0.1"
-  config.vm.network "forwarded_port", guest: 443, host: 8889, host_ip: "127.0.0.1"
 
   # Provision VM using Ansible playbook
   config.vm.provision "ansible" do |ansible|
@@ -22,7 +21,9 @@ Vagrant.configure("2") do |config|
     ansible.playbook = "playbook.yml"
     ansible.host_vars = {
       "default" => {
-        "deploy_environment" => "vagrant"
+        "deploy_environment" => "vagrant",
+        "django_debug" => 1,
+        "django_secret_key" => "debug_only_g62WlORMbo8iAcV7vKCKBQ=="
       }
     }
   end

deploy/inventory.example.yml

@@ -0,0 +1,5 @@
+all:
+  hosts:
+    example.com:
+      django_debug: 1
+      django_secret_key: debug_only_g62WlORMbo8iAcV7vKCKBQ==

deploy/playbook.yml

@@ -15,10 +15,6 @@
     project_dir: /srv/{{ project_name }}
     project_src_dir: "{{ project_dir }}/src"
 
-    django_settings:
-      debug: 1
-      secret_key: debug_only_g62WlORMbo8iAcV7vKCKBQ==
-
   tasks:
     - name: Vagrant specific tasks
       block:

deploy/templates/Caddyfile.j2

@@ -1,4 +1,4 @@
-:80 :443 {
+http://* {
     root * /srv
     file_server
 

deploy/templates/docker-compose.yml.j2

@@ -7,9 +7,9 @@ services:
     ports:
       - 8000:8000
     environment:
-      DEBUG: {{ django_settings.debug }}
+      DEBUG: {{ django_debug }}
       DATABASE_URL: sqlite:////app/db.sqlite3
-      SECRET_KEY: {{ django_settings.secret_key }}
+      SECRET_KEY: {{ django_secret_key }}
     volumes:
       - {{ project_dir }}/db.sqlite3:/app/db.sqlite3:z
       - static_files:/app/static