diff options
| -rw-r--r-- | DEPLOY.md | 39 | ||||
| -rw-r--r-- | README.md | 49 | ||||
| -rw-r--r-- | backend/README.md | 2 | ||||
| -rwxr-xr-x | backend/chrona.py (renamed from backend/histplorer.py) | 0 | ||||
| -rwxr-xr-x | backend/server.py | 2 | ||||
| -rw-r--r-- | index.html | 2 | ||||
| -rw-r--r-- | package.json | 2 | ||||
| -rwxr-xr-x | prebuild.sh | 7 | ||||
| -rw-r--r-- | src/README.md | 19 | ||||
| -rw-r--r-- | src/lib.ts | 2 |
10 files changed, 104 insertions, 20 deletions
diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..98c4077 --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,39 @@ +# Instructions for Deployment on an Apache server (version 2.4) on Ubuntu (22.04.1 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` by running `apt-get install libapache2-mod-wsgi-py3`. This is an Apache module for WSGI. + It's for running `backend/chrona.py` to serve tree-of-life data, and is used instead of CGI to avoid + starting a new process for each request. +1. Change some constants (automated by `prebuild.sh`) + - In `src/vite.config.js`: Set `base` to the URL path where Chrona will be accessible (eg: `'/chrona'`) + - In `src/lib.ts`: + - Set `SERVER_DATA_URL` to the URL where `backend/chrona.py` will be served + (eg: `'https://terryt.dev/chrona/data'`) + - Set `SERVER_IMG_PATH` to the URL path where images will be served (eg: `'/img/chrona'`). + If you place it within the `base` directory, you'll need to remember to move it when deploying + a newer production build. + - In `backend/chrona.py`: Set `DB_FILE` to where the database will be placed (eg: `'/usr/local/www/db/chrona.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 Chrona will be served. + The created directory should match up with the `base` value above (eg: `/var/www/terryt.dev/chrona/`). + 1. Copy over `backend/chrona.py`. The location should be accessible by Apache (eg: `/usr/local/www/wsgi-scripts/`). + Remember to set ownership and permissions as needed. + 1. Copy over `backend/hist_data/data.db`. The result should be denoted by the `DB_FILE` value above. + 1. Copy over the images in `backend/hist_data/img/`. There are a lot of them, so compressing them + before transfer is advisable (eg: `tar czf imgs.tar.gz backend/hist_data/img/`). The location should + match up with the `SERVER_IMG_PATH` value above (eg: `/var/www/terryt.dev/img/chrona/`). + 1. Edit the site's config file to serve chrona.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 /chrona/data /usr/local/www/wsgi-scripts/chrona.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 chrona.py. The `<Directory>` lines enable access for that location. @@ -1,12 +1,18 @@ -# Histplorer +# Chrona An interactive historical timeline. -[Available online](https://terryt.dev/tilo/). +Available online. ## Project Overview -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod -tempor incididunt ut labore et dolore magna aliqua. +The UI is largely coded in Typescript, using the [Vue](https://vuejs.org) +framework, with [Vite](https://vitejs.dev) as the build tool. Much of +the styling is done using [Tailwind](https://tailwindcss.com). Packages +are managed using [npm](https://www.npmjs.com) and [Node.js](https://nodejs.org). + +On the server side, tree data is served and generated using Python, with +packages managed using [Pip](https://pypi.org/project/pip). Tree data is +stored using [Sqlite](https://www.sqlite.org). ## Files @@ -16,6 +22,7 @@ tempor incididunt ut labore et dolore magna aliqua. - **LICENCE.txt**: This project's license (MIT) ### Client & Server - **src**: Contains most of the client-side code +- **tests**: Contains client-side unit tests - **index.html**: Holds code for the main page, into which code from 'src' will be included - **public**: Contains files to be copied unchanged in the client's production build - **backend**: Contains code for the server, and for generating history data @@ -25,30 +32,46 @@ tempor incididunt ut labore et dolore magna aliqua. - **postcss.config.js**: For configuring Tailwind - **tsconfig.json**: For configuring Typescript - **tsconfig.node.json**: For configuring Typescript +- **.eslintrc.js**: For configuring ESLint ### Other - **.gitignore**: Lists files to be ignored if using Git +- **DEPLOY.md**: Instructions for deployment on an Apache server on Ubuntu. +- **prebuild.sh**: Bash script for automating some steps of deployment. ## Setup Instructions +Note: Running your own version of the client and server should be straightforward, +but generating the database takes a long time. +More details are in `backend/hist_data/README.md`. + ### Client Side -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod -tempor incididunt ut labore et dolore magna aliqua. +1. If you don't have npm or Node.js installed, you can download a Node installer from + <https://nodejs.org/en/download>, which includes npm. This project was coded using version 16. +1. In this directory, run the command `npm install`, which install packages listed in + package.json, creating a `node_modules` directory to hold them. ### Server Side -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod -tempor incididunt ut labore et dolore magna aliqua. +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/hist_data/`. + See it's README for instructions. You'll likely need to install a few + packages using Pip. +1. To run the data server via `backend/server.py`, you'll need to install jsonpickle. + This can be done using `python -m pip install jsonpickle`. -### Running Histplorer + If you want to keep the installed package separate from your system's packages, + it's common practice to use [venv](https://docs.python.org/3/tutorial/venv.html). + +### Running Chrona 1. In `backend/`, run `./server.py`, which starts a basic HTTP server that provides history data on port 8000. 1. Running `npm run dev` starts the dev server. 1. Open a web browser, and navigate to <http://localhost:5713>. ## Deploying the Website - -Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod -tempor incididunt ut labore et dolore magna aliqua. +This is significantly dependent on the server platform. `DEPLOY.md` contains +instructions for deployment on an Apache server on an Ubuntu system. ## Licence -Histplorer is licensed under the MIT Licence. +Chrona is licensed under the MIT Licence. diff --git a/backend/README.md b/backend/README.md index cffbb81..6c7db61 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,6 +1,6 @@ # Files - `hist_data/`: Holds scripts for generating the history database and images -- `histplorer.py`: WSGI script that serves data from the history database +- `chrona.py`: WSGI script that serves data from the history database - `server.py`: Basic dev server that serves the WSGI script and image files - `tests/`: Holds unit testing scripts <br> Running all tests: `python -m unittest discover -s tests` <br> diff --git a/backend/histplorer.py b/backend/chrona.py index cd9a0be..cd9a0be 100755 --- a/backend/histplorer.py +++ b/backend/chrona.py diff --git a/backend/server.py b/backend/server.py index 5c3904a..d03215c 100755 --- a/backend/server.py +++ b/backend/server.py @@ -8,7 +8,7 @@ from typing import Iterable import os from wsgiref import simple_server, util import mimetypes -from histplorer import application +from chrona import application import argparse parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) @@ -3,7 +3,7 @@ <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <title>Histplorer</title> + <title>Chrona: Interactive Historical Timeline</title> <link rel="icon" href="/favicon.png" /> <link rel="preload" href="/font/Ubuntu-Regular.woff2" as="font" type="font/woff2" crossorigin/> </head> diff --git a/package.json b/package.json index 6c867f2..b135899 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "histplorer", + "name": "chrona", "private": true, "version": "0.1.0", "description": "An interactive historical timeline", diff --git a/prebuild.sh b/prebuild.sh new file mode 100755 index 0000000..9731276 --- /dev/null +++ b/prebuild.sh @@ -0,0 +1,7 @@ +#!/bin/bash +set -e + +sed -i -e "s|base: .*,|base: '/chrona/',|" vite.config.ts +sed -i -e "s|SERVER_DATA_URL = .*|SERVER_DATA_URL = (new URL(window.location.href)).origin + '/chrona/data/'|" \ + -e "s|SERVER_IMG_PATH = .*|SERVER_IMG_PATH = '/img/chrona/'|" src/lib.ts +sed -i -e 's|DB_FILE = .*|DB_FILE = "/usr/local/www/db/chrona.db"|' backend/chrona.py diff --git a/src/README.md b/src/README.md index 409e796..5ef7892 100644 --- a/src/README.md +++ b/src/README.md @@ -2,6 +2,21 @@ - **main.ts**: Included by ../index.html. Creates the main Vue component. - **App.vue**: The main Vue component. - **components**: - - **TestComponent.vue**: For testing. -- **index.css**: Included by main.ts. Provides Tailwind's CSS classes. + - **TimeLine.vue**: Displays an interactive timeline. + - **BaseLine.vue**: Displays a timeline overview. + - **InfoModal.vue**: Modal displaying event info. + - **SearchModal.vue**: Modal providing a search bar. + - **SettingsModal.vue**: Modal displaying configurable settings. + - **HelpModal.vue**: Modal displaying help info. + - **LoadingModal.vue**: Displays a loading indicator. + - **SButton.vue**: Simple button component. + - **IconButton.vue**: Simple button component containing an SVG icon. + - **SCollapsible.vue**: Simple collapsible-content component. + - **icon**: Contains components that display SVG icons. +- **store.ts**: App global storage. +- **lib.ts**: Holds project-wide globals. +- **util.ts**: Holds utility functions. +- **rbtree.ts**: Red-black tree implementation. +- **index.css**: Included by main.ts. Provides Tailwind's CSS classes. - **vite-env.d.ts**: From Vite's template files. +- **global.d.ts**: Temporary typescript overrides. @@ -1,5 +1,5 @@ /* - * Common project globals + * Project-wide globals */ import {moduloPositive, intToOrdinal, getNumTrailingZeros} from './util'; |