Update readme
This commit is contained in:
Rumperuu
parent
7f2be9ea9f
commit
ca2d1e8aab
1 changed files with 106 additions and 110 deletions
216
README.md
216
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
|
## Current Status
|
||||||
|
|
||||||
*Master:* [](https://travis-ci.org/Pear-Trading/Foodloop-Server)
|
| Branch | Status |
|
||||||
|
|---------------|------------------ |
|
||||||
|
| `master` | [](https://travis-ci.org/Pear-Trading/Foodloop-Server) |
|
||||||
|
| `development` | [](https://travis-ci.org/Pear-Trading/Foodloop-Server) |
|
||||||
|
|
||||||
*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 server app. is written in [Perl](https://www.perl.org/).
|
||||||
the tests:
|
|
||||||
|
|
||||||
- `cpanm --installdeps .`
|
| Technology | Description | Link |
|
||||||
- `prove -lr`
|
|-------------|---------------------|---------------------|
|
||||||
|
| Mojolicious | Perl Web framework | [Link][mojolicious] |
|
||||||
|
| PostgreSQL | Relational database | [Linke][postgresql] |
|
||||||
|
|
||||||
To run the main framework against a PostgreSQL backend, assuming you have
|
[mojolicious]: https://mojolicious.org/
|
||||||
`postgres` installed, you will need some extra dependencies first:
|
[postgresql]: https://www.postgresql.org/
|
||||||
|
|
||||||
- `cpanm --installdeps . --with-feature postgres`
|
## Features
|
||||||
- `PEAR_TEST_PG=1 prove -lr`
|
|
||||||
|
|
||||||
## Setting Up Minion
|
This server app. provides:
|
||||||
|
|
||||||
To set up Minion support, you will need to create a database and user for
|
- user creation, updating and deletion;
|
||||||
it to connect to.
|
- organisation creation, updating and deletion;
|
||||||
In production his should be a PostgreSQL database, however SQLite can be used
|
- transaction logging;
|
||||||
in testing.
|
- transaction history analysis; and
|
||||||
|
- leaderboard generation.
|
||||||
|
|
||||||
To use the SQLite version:
|
## Installation
|
||||||
|
|
||||||
1. Install the SQLite dependencies:
|
1. Clone the repo. to your dev. environment (`git clone git@github.com:Pear-Trading/FoodLoop-Server.git`);
|
||||||
- `cpanm --installdeps --with-feature sqlite .`
|
1. enter the new directory (`cd FoodLoop-Server`);
|
||||||
2. Ensure that the following is in your configuration file:
|
1. install the dependencies:
|
||||||
- ```
|
|
||||||
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:
|
|
||||||
- ```shell script
|
- ```shell script
|
||||||
cpanm --installdeps . \
|
cpanm --installdeps . \
|
||||||
--with-feature=sqlite \
|
--with-feature=sqlite \
|
||||||
--with-feature=codepoint-open
|
--with-feature=codepoint-open
|
||||||
```
|
```
|
||||||
- See [Troubleshooting](#troubleshooting) if you encounter difficulties.
|
- if you are using a PostgreSQL database, replace `--with-feature=sqlite` with `--with-feature=postgres`.
|
||||||
1. Install the database:
|
1. install the database:
|
||||||
- `./script/deploy_db install -c 'dbi:SQLite:dbname=foodloop.db'`
|
- development supports both SQLite and PostgreSQL, however production uses PostgreSQL;
|
||||||
1. Set up the development users:
|
- 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`
|
- `./script/pear-local_loop dev_data --force`
|
||||||
- **DO NOT RUN ON PROD.**
|
- **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`
|
- `./script/pear-local_loop minion worker`
|
||||||
1. Import ward data (see [instructions](#importing-ward-data) above)
|
1. import ward data:
|
||||||
1. Set up postcodes (see [instructions](#setting-up-entity-postcodes) above)
|
1. Download the CSV(s) from [here](https://www.doogal.co.uk/PostcodeDownloads.php); and
|
||||||
1. Set up your `pear-local_loop.⟨environment⟩.conf` file in the project root
|
1. run the following command:
|
||||||
1. Ensure you have a copy of the FCM service user credentials saved in the project root (`localspend-47012.json`)
|
- ```shell script
|
||||||
1. Start the application:
|
./script/pear-local_loop minion job \
|
||||||
- `morbo script/pear-local_loop -l http://*:3000`
|
--enqueue 'csv_postcode_import' \
|
||||||
- You can modify the host and port as needed.
|
--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:
|
To upgrade the database after making changes to commit:
|
||||||
|
|
||||||
1. Increment the `$VERSION` number in `lib/Pear/LocalLoop/Schema.pm`
|
1. Increment the `$VERSION` number in `lib/Pear/LocalLoop/Schema.pm`;
|
||||||
1. `./script/deploy_db write_ddl -c 'dbi:SQLite:dbname=foodloop.db'`
|
1. run `./script/deploy_db write_ddl -c 'dbi:SQLite:dbname=foodloop.db'`; and
|
||||||
1. `./script/deploy_db upgrade -c 'dbi:SQLite:dbname=foodloop.db'`
|
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/<username>/perl5’ when running `cpanm` commands
|
## Code Formatting
|
||||||
|
|
||||||
Install `local::lib` by running the following commands:
|
TODO
|
||||||
|
|
||||||
```
|
## Documentation
|
||||||
cpanm --local-lib=~/perl5 local::lib && eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
|
|
||||||
```
|
|
||||||
|
|
||||||
You will have to do every time you open a new Terminal window.
|
TODO
|
||||||
To make it permanent, follow [these steps](https://www.cpan.org/modules/by-module/lib/local-lib-2.000018.readme).
|
|
||||||
|
|
||||||
## ‘Can't load application from file "<path-to-repo>/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
|
||||||
|
|
|
||||||
Reference in a new issue