Pear-Trading
/
Foodloop-Server
Archived
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update readme

This commit is contained in:
Rumperuu 2021-03-20 09:40:32 +00:00
parent 7f2be9ea9f
commit ca2d1e8aab
1 changed files with 106 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

216
README.md
View File

@ -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/<username>/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 "<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