Add deployment documentation

4 files changed, 78 insertions, 9 deletions

diff --git a/.gitignore b/.gitignore
index 1194307..7d5fe2d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,9 +1,9 @@
 /package-lock.json
 /node_modules/
 /dist/
-/public/img/
+/backend/__pycache__
 
-# Backend files
+# Database files
 /backend/tolData/data.db
 /backend/tolData/otol/*.tgz
 /backend/tolData/otol/*.json
@@ -30,4 +30,3 @@
 /backend/tolData/pickedEnwikiLabels.txt
 /backend/tolData/pickedNodes.txt
 /backend/tolData/pickedNames.txt
-/backend/__pycache__
diff --git a/DEPLOY.md b/DEPLOY.md
new file mode 100644
index 0000000..43ccccc
--- /dev/null
+++ b/DEPLOY.md
@@ -0,0 +1,56 @@
+# Instructions for Deployment on an Apache server (version 2.4) on Ubuntu (20.04 LTS)
+
+1.  Set up the server environment
+    -   If Python3 and jsonpickle aren't installed, this can be done using
+        `apt-get update; apt-get install python3 python3-jsonpickle`.
+    -   Install `mod_wsgi`, an Apache module for WSGI. This is for running `backend/tilo.py` to serve
+        tree-of-life data, and is used instead of CGI to avoid starting a new process for each request.
+        You can find instructions
+        [here](https://modwsgi.readthedocs.io/en/master/user-guides/quick-installation-guide.html). The below
+        is a rough summary of setup on Ubuntu.
+        1.  Install some prerequisites
+            1.  `apt-get update`
+            1.  `sudo aptitude install apache2-dev python3-dev`
+        1.  Download and build the module
+            1.  Download the [source](https://github.com/GrahamDumpleton/mod_wsgi/releases) into `mod_wsgi-4.9.2.tar.gz`
+            1.  `tar xvfz mod_wsgi-4.9.2.tar.gz`
+            1.  `cd mod_wsgi-4.9.2`
+            1.  `./configure --with-python=/usr/bin/python3`
+            1.  `make`
+        1.  Install and enable the module
+            1.  `sudo make install`
+            1.  Create /etc/apache2/mods-available/wsgi.load, and add the line
+                `LoadModule wsgi_module /usr/lib/apache2/modules/mod_wsgi.so`
+            1.  `sudo a2enmod wsgi`
+            1.  `sudo systemctl restart apache2`
+1.  Change some constants (automated by `prebuild.sh`)
+    -   In `src/vite.config.js`: Set `base` to the URL path where Tilo will be accessible (eg: `'/tilo'`)
+    -   In `src/lib.ts`:
+        -   Set `SERVER_DATA_URL` to the URL where `backend/tilo.py` will be served
+            (eg: `'https://terryt.dev/tilo/data'`)
+        -   Set `SERVER_IMG_PATH` to the URL path where images will be served (eg: `'/img/tilo'`).
+            If you place it within the `base` directory, you'll need to remember to move it when deploying
+            a newer production build.
+    -   In `backend/tilo.py`: Set `dbFile` to where the database will be placed (eg: `'/usr/local/www/db/tilo.db'`)
+1.  Generate the client-side production build <br>
+    Run `npm run build`. This generates a directory `dist/`.
+1.  Copy files to the server (using ssh, sftp, or otherwise)
+    1.  Copy `dist/` into Apache's document root, into the directory where Tilo will be served.
+        The created directory should match up with the `base` value above (eg: `/var/www/terryt.dev/tilo/`).
+    1.  Copy over `backend/tolData/data.db`. The result should be denoted by the `dbFile` value above.
+        Remember to set ownership and permissions as needed.
+    1.  Copy over the images in `backend/tolData/img/`. There are a lot of them, so compressing them
+        before transfer is advisable (eg: `tar czf imgs.tar.gz backend/tolData/img/`). The location should
+        match up with the `SERVER_IMG_PATH` value above (eg: `/var/www/terryt.dev/img/tilo/`).
+    1.  Copy over `backend/tilo.py`. The location should be accessible by Apache (eg: `/usr/local/www/wsgi-scripts/`).
+    1.  Edit the site's config file to serve tilo.py. The file path will likely be something like
+        `/etc/apache2/sites-available/terryt.dev-le-ssl.conf`, and the edit should add lines like the following,
+        likely within a `<VirtualHost>` section:
+        
+            WSGIScriptAlias /tilo/data /usr/local/www/wsgi-scripts/tilo.py
+            <Directory /usr/local/www/wsgi-scripts>
+                Require all granted
+            </Directory>
+        
+        The first `WSGIScriptAlias` parameter should match the URL path in `SERVER_URL`, and the second should
+        be the location of tilo.py. The `<Directory>` lines enable access for that location.
diff --git a/README.md b/README.md
index ebda699..5221183 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,6 @@ stored using [Sqlite](https://www.sqlite.org).
 -   **package.json**:       Contains npm project information, such as package dependencies.
 -   **package-lock.json**:  Auto-generated by npm. Used for replicable installations.
 -   **LICENCE.txt**:        This project's license (MIT).
--   **.gitignore**:         Lists files to be ignored if using [Git](https://git-scm.com/downloads).
 ### Client &amp; Server
 -   **src**:                Contains most of the client-side code.
 -   **index.html**:         Holds code for the main page, into which code from 'src' will be included.
@@ -30,6 +29,10 @@ stored using [Sqlite](https://www.sqlite.org).
 -   **tailwind.config.js**: For configuring Tailwind.
 -   **postcss.config.js**:  For configuring Tailwind.
 -   **tsconfig.json**:      For configuring Typescript.
+### Other
+-   **.gitignore**:         Lists files to be ignored if using [Git](https://git-scm.com/downloads).
+-   **DEPLOY.md**:          Instructions for deployment on an Apache server on Ubuntu.
+-   **prebuild.sh**:        Bash script for automating some steps of deployment.
 
 ## Setup Instructions
 
@@ -46,8 +49,8 @@ in backend/data/README.md.
 ### Server Side
 1.  If you don't have Python 3 installed, see <https://www.python.org/downloads>.
     The package manager Pip is included.
-1.  The database used by the server is generated using scripts in backend/data/.
-    See it's README.md for instructions. You'll likely need to install a few
+1.  The database used by the server is generated using scripts in `backend/data/`.
+    See it's README for instructions. You'll likely need to install a few
     packages using Pip.
 1.  To run the dev server, you'll need to install jsonpickle. This can be done
     using `python -m pip install jsonpickle`. If you want to keep the installed
@@ -55,12 +58,16 @@ in backend/data/README.md.
     the 'venv' module.
 
 ### Running Tilo
-1.  In the backend/ directory, run `./server.py`, which starts a basic HTTP server that provides
+1.  In `backend/`, run `./server.py`, which starts a basic HTTP server that provides
     tree-of-life data on port 8000.
-1.  In this directory, or somewhere in src/, run `npm run dev`. This starts a dev server that
+1.  In this directory, or somewhere in `src/`, run `npm run dev`. This starts a dev server that
     provides Tilo's user interface on port 3000.
 1.  Open a web browser, and navigate to <http://localhost:3000>.
 
+## Deploying the Website
+This is significantly dependent on the server platform. `DEPLOY.md` contains
+instructions for deployment on an Apache server on an Ubuntu system.
+
 ## Licence
 
-Tilo is licensed under the MIT licence, provided in LICENSE.txt
+Tilo is licensed under the MIT licence, provided in `LICENSE.txt`
diff --git a/prebuild.sh b/prebuild.sh
new file mode 100755
index 0000000..1e2a268
--- /dev/null
+++ b/prebuild.sh
@@ -0,0 +1,7 @@
+#!/bin/bash
+set -e
+
+sed -i -e "s|base: .*,|base: '/tilo/',|" vite.config.js
+sed -i -e "s|SERVER_DATA_URL = .*|SERVER_DATA_URL = 'https://terryt.dev/tilo/data'|" \
+	-e "s|SERVER_IMG_PATH = .*|SERVER_IMG_PATH = '/img/tilo/'|" src/lib.ts
+sed -i -e 's|dbFile = .*|dbFile = "/usr/local/www/db/tilo.db"|' backend/tilo.py