From ca2d1e8aabc26b94d7768e79901e657e22003a5f Mon Sep 17 00:00:00 2001 From: Rumperuu Date: Sat, 20 Mar 2021 09:40:32 +0000 Subject: [PATCH] Update readme --- README.md | 216 +++++++++++++++++++++++++++--------------------------- 1 file changed, 106 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index 8cf1488..030060a 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,142 @@ -# LocalSpend - Server +# LocalSpend (Server) -This repository contains the server for the LocalSpend system. +Looking to discover if the value of spending local can be measured, understood and shown. + +This repository contains the server application for the LocalSpend system. See also: + +* the [Web application](https://github.com/Pear-Trading/Foodloop-Web); and +* the [mobile application](https://github.com/Pear-Trading/LocalSpend-Tracker). ## Current Status -*Master:* [![Build Status](https://travis-ci.org/Pear-Trading/Foodloop-Server.svg?branch=master)](https://travis-ci.org/Pear-Trading/Foodloop-Server) +| Branch | Status | +|---------------|------------------ | +| `master` | [![Build Status](https://travis-ci.org/Pear-Trading/Foodloop-Server.svg?branch=master)](https://travis-ci.org/Pear-Trading/Foodloop-Server) | +| `development` | [![Build Status](https://travis-ci.org/Pear-Trading/Foodloop-Server.svg?branch=development)](https://travis-ci.org/Pear-Trading/Foodloop-Server) | -*Development:* [![Build Status](https://travis-ci.org/Pear-Trading/Foodloop-Server.svg?branch=development)](https://travis-ci.org/Pear-Trading/Foodloop-Server) +## Table of Contents -# Test Environment +* [Tech Stack](#tech-stack) +* [Features](#features) +* [Installation](#installation) +* [Configuration](#configuration) +* [Usage](#usage) +* [Testing](#testing) +* [Code Formatting](#code-formatting) +* [Documentation](#documentation) +* [Acknowledgments](#acknowledgements) +* [License](#license) +* [Contact](#contact) -## Running Tests +## Technology Stack -To run the main test framework, first install all the dependencies, then run -the tests: +The server app. is written in [Perl](https://www.perl.org/). -- `cpanm --installdeps .` -- `prove -lr` +| Technology | Description | Link | +|-------------|---------------------|---------------------| +| Mojolicious | Perl Web framework | [Link][mojolicious] | +| PostgreSQL | Relational database | [Linke][postgresql] | -To run the main framework against a PostgreSQL backend, assuming you have -`postgres` installed, you will need some extra dependencies first: +[mojolicious]: https://mojolicious.org/ +[postgresql]: https://www.postgresql.org/ -- `cpanm --installdeps . --with-feature postgres` -- `PEAR_TEST_PG=1 prove -lr` +## Features -## Setting Up Minion +This server app. provides: -To set up Minion support, you will need to create a database and user for -it to connect to. -In production his should be a PostgreSQL database, however SQLite can be used -in testing. +- user creation, updating and deletion; +- organisation creation, updating and deletion; +- transaction logging; +- transaction history analysis; and +- leaderboard generation. -To use the SQLite version: +## Installation -1. Install the SQLite dependencies: - - `cpanm --installdeps --with-feature sqlite .` -2. Ensure that the following is in your configuration file: - - ``` - minion => { - SQLite => 'sqlite:minion.db', - }, - ``` - -This will then use an SQLite DB for the Minion backend, using `minion.db` as -the database file. - -To start the minion itself, run this command: -- `./script/pear-local_loop minion worker` - -## Importing Ward Data - -To import ward data: - -1. Download CSV(s) from [here](https://www.doogal.co.uk/PostcodeDownloads.php) -1. Run the following command: - - ```shell script - ./script/pear-local_loop minion job \ - --enqueue 'csv_postcode_import' \ - --args '[ "⟨ path to CSV ⟩ ]' - ``` - -## Setting Up Entity Postcodes - -1. Import Code-Point Open: - - included in `etc/` - - `./script/pear-local_loop codepoint_open --outcodes LA1` -1. Assign postcodes: - - ```shell script - ./script/pear-local_loop minion job \ - --enqueue entity_postcode_lookup - ``` - -## Example PostgreSQL setup - -``` -# Example commands - probably not the best ones -# TODO come back and improve these with proper ownership and DDL rights -sudo -u postgres createuser minion -sudo -u postgres createdb localloop_minion -sudo -u postgres psql -psql=# alter user minion with encrypted password 'abc123'; -psql=# grant all privileges on database localloop_minion to minion; -``` - -# Development Environment - -There are a couple of setup steps to getting a development environment ready. - -## First Time Setup - -1. Decide if you're using SQLite or PostgreSQL locally. - - Development supports both, however production uses PostgreSQL. - - For this example we will use SQLite. - - As the default config. is set up for this, no configuration changes are -needed initially. -1. Install dependencies: +1. Clone the repo. to your dev. environment (`git clone git@github.com:Pear-Trading/FoodLoop-Server.git`); +1. enter the new directory (`cd FoodLoop-Server`); +1. install the dependencies: - ```shell script cpanm --installdeps . \ --with-feature=sqlite \ --with-feature=codepoint-open ``` - - See [Troubleshooting](#troubleshooting) if you encounter difficulties. -1. Install the database: - - `./script/deploy_db install -c 'dbi:SQLite:dbname=foodloop.db'` -1. Set up the development users: + - if you are using a PostgreSQL database, replace `--with-feature=sqlite` with `--with-feature=postgres`. +1. install the database: + - development supports both SQLite and PostgreSQL, however production uses PostgreSQL; + - for this example we will use SQLite; + - as the default config. is set up for this, no configuration changes are needed initially. + - run `./script/deploy_db install -c 'dbi:SQLite:dbname=foodloop.db'`. +1. set up the development users: - `./script/pear-local_loop dev_data --force` - **DO NOT RUN ON PROD.** -1. Start the minion: +1. start the [minion](https://docs.mojolicious.org/Minion) job queue: - `./script/pear-local_loop minion worker` -1. Import ward data (see [instructions](#importing-ward-data) above) -1. Set up postcodes (see [instructions](#setting-up-entity-postcodes) above) -1. Set up your `pear-local_loop.⟨environment⟩.conf` file in the project root -1. Ensure you have a copy of the FCM service user credentials saved in the project root (`localspend-47012.json`) -1. Start the application: - - `morbo script/pear-local_loop -l http://*:3000` - - You can modify the host and port as needed. +1. import ward data: + 1. Download the CSV(s) from [here](https://www.doogal.co.uk/PostcodeDownloads.php); and + 1. run the following command: + - ```shell script + ./script/pear-local_loop minion job \ + --enqueue 'csv_postcode_import' \ + --args '[ "⟨ path to CSV ⟩ ]' + ``` +1. set up postcodes: + 1. import [Code-Point Open](https://www.ordnancesurvey.co.uk/business-government/products/code-point-open): + - a copy is included in `etc/`; + - run `./script/pear-local_loop codepoint_open --outcodes LA1` + 1. assign postcodes: + - ```shell script + ./script/pear-local_loop minion job \ + --enqueue entity_postcode_lookup + ``` -## Database Scripts +## Configuration + +App. configuration settings are found in `pear-local_loop.⟨environment⟩.conf`. + +[Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/) (FCM) credentials should be placed in a file called `localspend-47012.json` in root. + +## Usage + +- Run `morbo script/pear-local_loop -l http://*:3000` to start the server; and +- run `./script/pear-local_loop minion worker` to start the Minion asynchronous job scheduler. + +### Database Scripts To upgrade the database after making changes to commit: -1. Increment the `$VERSION` number in `lib/Pear/LocalLoop/Schema.pm` -1. `./script/deploy_db write_ddl -c 'dbi:SQLite:dbname=foodloop.db'` -1. `./script/deploy_db upgrade -c 'dbi:SQLite:dbname=foodloop.db'` +1. Increment the `$VERSION` number in `lib/Pear/LocalLoop/Schema.pm`; +1. run `./script/deploy_db write_ddl -c 'dbi:SQLite:dbname=foodloop.db'`; and +1. run `./script/deploy_db upgrade -c 'dbi:SQLite:dbname=foodloop.db'`. -To redo leaderboards: +Run `./script/pear-local_loop recalc_leaderboards` to update the leaderboards. -1. `./script/pear-local_loop recalc_leaderboards` +## Testing -# Troubleshooting +- Run `prove -lr` to run the full test suite using [Test-Simple](https://metacpan.org/release/Test-Simple) (when using an SQLite database); and +- run `PEAR_TEST_PG=1 prove -lr` to run the full test suite (when using a PostgreSQL database). -## ‘Can't write to /usr/local/share/perl/5.30.0 and /usr/local/bin: Installing modules to /home//perl5’ when running `cpanm` commands +## Code Formatting -Install `local::lib` by running the following commands: +TODO -``` - cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib) -``` +## Documentation -You will have to do every time you open a new Terminal window. -To make it permanent, follow [these steps](https://www.cpan.org/modules/by-module/lib/local-lib-2.000018.readme). +TODO -## ‘Can't load application from file "/script/pear-local_loop": Can't locate Data/UUID.pm in @INC (you may need to install the DATA::UUID module)’ when running server +## Acknowledgements -Ensure you have run the `cpan --installdeps` command. +LocalLoop is the result of collaboration between the [Small Green Consultancy](http://www.smallgreenconsultancy.co.uk/), [Shadowcat Systems](https://shadow.cat/), [Independent Lancaster](http://www.independent-lancaster.co.uk/) and the [Ethical Small Traders Association](http://www.lancasteresta.org/). + +## License + +This project is released under the [MIT license](https://mit-license.org/). + +## Contact + +| Name | Link(s) | +|----------------|-------------------| +| Mark Keating | [Email][mkeating] | +| Michael Hallam | [Email][mhallam] | + +[mkeating]: mailto:m.keating@shadowcat.co.uk +[mhallam]: mailto:info@lancasteresta.org