From b06b3a9cb3ae772202f522ae085446a040736c95 Mon Sep 17 00:00:00 2001 From: Terry Truong Date: Mon, 11 Jul 2022 19:39:40 +1000 Subject: Add deployment documentation --- .gitignore | 5 ++--- DEPLOY.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 19 +++++++++++++------ prebuild.sh | 7 +++++++ 4 files changed, 78 insertions(+), 9 deletions(-) create mode 100644 DEPLOY.md create mode 100755 prebuild.sh 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
+ 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 `` section: + + WSGIScriptAlias /tilo/data /usr/local/www/wsgi-scripts/tilo.py + + Require all granted + + + The first `WSGIScriptAlias` parameter should match the URL path in `SERVER_URL`, and the second should + be the location of tilo.py. The `` 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 & 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 . 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 . +## 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 -- cgit v1.2.3