Foodloop-Server/README.md

LocalSpend (Server)

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; and
• the mobile application.

Current Status

Branch	Status
master
development

Table of Contents

• Tech Stack
• Features
• Installation
• Configuration
• Usage
• Testing
• Code Formatting
• Documentation
• Acknowledgments
• License
• Contact

Technology Stack

The server app. is written in Perl.

Admin. portal pages are templated using HTML::EP.

Technology	Description	Link
Mojolicious	Perl Web framework	Link
PostgreSQL	Relational database managment system	Link
SQLite	Relational database managment system	Link

Features

This server app. provides:

• user creation, updating and deletion;
• organisation creation, updating and deletion;
• an admin. management portal;
• transaction logging;
• transaction history analysis; and
• leaderboard generation.

Installation

1. Clone the repo. to your dev. environment (git clone git@github.com:Pear-Trading/FoodLoop-Server.git);
2. enter the new directory (cd FoodLoop-Server);
3. install the dependencies:

   • cpanm --installdeps . \
     --with-feature=sqlite \
     --with-feature=codepoint-open
     

   • if you are using a PostgreSQL database, replace --with-feature=sqlite with --with-feature=postgres.
4. install the database:
   • run ./script/deploy_db install -c 'dbi:SQLite:dbname=foodloop.db';
   • development supports both SQLite and PostgreSQL (production uses PostgreSQL);
   • for this example we will use SQLite; so
   • as the default config. is set up for this, no configuration changes are needed initially.
5. set up the development users:
   • ./script/pear-local_loop dev_data --force
   • DO NOT RUN ON PROD!
6. start the Minion job scheduler:
   • ./script/pear-local_loop minion worker
7. import ward data:
   1. Download the CSV(s) from here; and
   2. run the following command:

      •     ./script/pear-local_loop minion job \
            --enqueue 'csv_postcode_import'  \
            --args '[ "⟨ path to CSV ⟩" ]'
            ```
        

8. set up postcodes:
   1. import Code-Point Open: - a copy is included in etc/; - run ./script/pear-local_loop codepoint_open --outcodes LA1
      1. assign postcodes:

      ./script/pear-local_loop minion job
      --enqueue entity_postcode_lookup ```

Configuration

App. configuration settings are found in pear-local_loop.⟨environment⟩.conf.

Firebase Cloud Messaging (FCM) credentials should be placed in a file called localspend-47012.json in root. This file is not tracked by Git; ask another developer for a copy.

Default user credentials are found in lib/Pear/LocalLoop/Command/dev_data.pm.

Usage

• Run ./script/pear-local_loop minion worker to start the Minion asynchronous job scheduler; and
• run morbo script/pear-local_loop -l http://*:3000 to start the server on the specific hostname and port.

Database Scripts

To upgrade the database after making changes to commit:

1. Increment the $VERSION number in lib/Pear/LocalLoop/Schema.pm;
2. run ./script/deploy_db write_ddl -c 'dbi:SQLite:dbname=foodloop.db'; and
3. run ./script/deploy_db upgrade -c 'dbi:SQLite:dbname=foodloop.db'.

Run ./script/pear-local_loop recalc_leaderboards to update the leaderboards.

Testing

• Run prove -lr -j 9 to run the full test suite using Test-Simple (when using an SQLite database); and
• run PEAR_TEST_PG=1 prove -lr -j 9 to run the full test suite (when using a PostgreSQL database).

Test files are found in the t/ directory.

Code Formatting

Run for f in ./lib/**/*.pm; do perltidy -b $f; done to format all Perl files with Perl-Tidy (there is no built-in option to format files recursively). This will produce backup files with .bak extensions, so run find . -name '*.bak' -delete to clean up your local copy if you are happy with the formatted files.

Run perlcritic lib to lint all Perl files with Perl-Critic.

Documentation

TODO

Acknowledgements

LocalLoop is the result of collaboration between the Small Green Consultancy, Shadowcat Systems](https://shadow.cat/), Independent Lancaster and the Ethical Small Traders Association.

License

This project is released under the MIT license.

Contact

Name	Link(s)
Mark Keating	Email
Michael Hallam	Email