diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 83 |
1 files changed, 63 insertions, 20 deletions
@@ -1,27 +1,70 @@ # Tilo -Provides an interactive visualisation of the biological Tree of Life. + +A visual explorer for the biological Tree of Life. + +## Project Overview + +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 -- package.json: Contains project information, including package dependencies. -- src: Contains most of the client-side code. -- index.html: Holds code for the main page, into which code from 'src' will be included. -- backend: Contains code for the server, and generating tree-of-life data -- vite.config.js: For configuring Vite. -- tailwind.config.js: For configuring Tailwind. -- postcss.config.js: For configuring Tailwind. -- tsconfig.json: For configuring Typescript. -- .gitignore: Lists files to be ignored by Git. -- public: Contains files to be copied unchanged when building for production. - -## Overview -(TODO) + +### Project Level +- **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 by Git. +### 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. +- **public**: Contains files to be copied unchanged in the production-build of the UI. +- **backend**: Contains code for the server, and for generating tree-of-life data. +### Configuration +- **vite.config.js**: For configuring Vite. +- **tailwind.config.js**: For configuring Tailwind. +- **postcss.config.js**: For configuring Tailwind. +- **tsconfig.json**: For configuring Typescript. ## Setup Instructions -(TODO) -## +Note: Running your own version of the client and server should be +straightforward, but generating the database will take a long time. +More details are in backend/data/README.md. + +### Base Requirements +- **[Python](https://www.python.org/downloads)**: For running server-side code, and generating the database. +- **Pip**: For installing Python packages. Included in the Python download. +- **[Git](https://git-scm.com/downloads)** (optional): For downloading and viewing snapshots of the project. + +### Client Side +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 +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 + 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 + package separate from your system's packages, it's common practice to use + the 'venv' module. + +### Running Tilo +1. In the backend/ directory, 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 + provides Tilo's user interface on port 3000. +1. Open a web browser, and navigate to <http://localhost:3000>. + +## Licence -During development, a client request to the server on the same machine -would be blocked due to the Same Origin Policy. This is avoided by -adding an 'Access-Control-Allow-Origin: *' header to server responses. -This should be disabled during production. +Tilo is licensed under the MIT licence, provided in LICENSE.txt |