Readme

You just found the Drop App (first version of Boxtribute - an web-app, which makes it easy for organisations to source, store and distribute donated goods to people in need in a fair and dignified way). This is currently in the process of being replaced by Boxtribute 2.0.

Dropapp was initially developed for Drop In The Ocean - a Norwegian NGO who is working in three refugee camps throughout Greece. Other users include Samos Volunteers, Europe Cares, Hermine, The Free Shop Lebanon, Intereuropean Human Aid Association (IHA) and Movement on the Ground.

We have evolved the app to now be centrally hosted so we can offer the product to many more organisations, and are working constantly to improve the system and connect donor and distributor organisations with each other.

If you are interested in being part of this project, write us at [email protected]! You can also check out our website for more details about the kind of help we need on this project.

Preparation for Installation

• Install Docker

• Install PHP 8.2 or later.

• Ensure you have the mbstring, curl, mysql and xdebug PHP extensions installed. On Ubuntu:

   apt install php-curl php-mbstring php-mysql php-xdebug
  

How do I get set up?

0. Clone this repo. If you're running Ubuntu, you may need to set write permissions to the templates folder for Docker.

   git clone https://github.com/boxwise/dropapp
   chmod -R 777 dropapp/templates (not generally recommended - ToDo Fix bug for Ubuntu users) 
   

1. You first need to install 'composer' (we suggest making it available globally)

   curl -s https://getcomposer.org/installer | php
   mv composer.phar /usr/local/bin/composer
   

2. You can install the required dependencies then using

   composer install
   

3. To configure the app, copy /library/config.php.default and remove the .default in the filename. Then fill the Auth0 credentials from the Auth0 client. Please check docs/auth0.md for further information regarding Auth0.

4. To run the application, we assume you have Docker installed. You can then run:

   docker-compose up
   

   Alternatively, you can run using the PHP development server

   php -S localhost:8000 gcloud-entry.php 
   

5. To initialize the database for the first time, you should run this command to create the schema:

   vendor/bin/phinx migrate -e development
   

   The database seed db/init.sql is generated in v2 and copied from there.

6. If you want to additionally want to connect the users from the seed to auth0 and populate the db table cms_usergroups_roles then open a browser and request http://localhost:8100/cron/reseed-auth0.php

Accessing the app

Once the docker containers are running the app is accessible at http://localhost:8100/

After this you should be able to login to the app using the password Browser_tests and one of the following emails:

• [email protected] (God User)

BoxAid (all have access to one base called Lesvos):

• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]

BoxCare (there are 3 bases associated - Thessaloniki, Samos, Athens):

• [email protected]
• [email protected] (Coordinator at bases Thessaloniki and Samos)
• [email protected] (Volunteer at bases Thessaloniki and Samos)
• [email protected]
• [email protected]
• [email protected]
• volunteer@thessaloniki.
• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected] (only for label creation)

Our dev environment recommendation

Most of us use VSCode as a code editor and MySQL workbench for database access.

Linting / Auto formatting

So we don't have to think/argue over code conventions, we're using the php-cs-fixer automatic code formatter.

CircleCI will fail your Pull-Request if there is any code requiring linting fixes.

If you're using VSCode, the vscode-php-cs-fixer extension will be suggested automatically and apply auto format on save.

Alternatively, you can run

 php vendor/friendsofphp/php-cs-fixer/php-cs-fixer fix . --rules @PhpCsFixer

in the root manually.

Debugging

We have enabled XDebug remote debugging in the default Docker configuration, so you can step through your code. Please run docker-compose up --build next time you start up your server to update your docker image.

If you're using VS Code, if you install the PHP Debug extension and start the 'Listen for XDebug' configuration, you can then set breakpoints in your code.

Please be aware that only breakpoints are caught which sit in a line with executable code.

Debugging For linux users

Docker containers running on linux cannot resolve the address host.docker.internal to an ip-address. To use Xdebug on linux you have to specify the internal ip-address of the docker container in docker-compose.yaml. To find out your internal docker address run

    docker inspect -f '{{range .NetworkSettings.Networks}}{{.Gateway}}{{end}}' <NAME OF YOUR DOCKER CONTAINER>

Enter the address in docker-compose.yaml here:

    environment:
        XDEBUG_CONFIG: remote_host=172.19.0.1 

Database and migrations

Command-line access

If you want to connect to the MySQL server from your host machine, you can do this using

docker exec -it <name of the db docker container> mysql -u root -p

The mysql server in your docker container is also reachable on port 9906 of your localhost

mysql --host=127.0.0.1 --port=9906 -u root -p

The password for the root-user for the db dropapp_dev is dropapp_root.

MySQL workbench access

Most of use use workbench to access the MySQL database. To establish a connection you need to enter your localhost-address, e.g. 127.0.0.1, for 'Hostname' and 9906 for 'Port'.

Phinx migrations

We're using Phinx to run database migrations.

To migrate to the current database version run

    vendor/bin/phinx migrate

To create an migration run

    vendor/bin/phinx create <NameOfMigrationInCamelCaseFormat>

It creates an file in db/migrations. Please use this file to write your db migration.

Cypress and testing

We use Cypress for Browser-test. To run Cypress tests on your local environment, please

1. Install Cypress via direct Download
2. Set the variable baseURL to your local address, e.g. localhost:8100 in cypress.json.
3. Set the env variable auth0Domain to the development Auth0 tenant, e.g. boxtribute-dev.eu.auth0.com in cypress.json.
4. Open Cypress and this repo in Cypress

Cypress Tests fail due to unsynchronized users with Auth0

If the tests 2.4 and 2.9 fail, check

• if the user with [email protected] exists in Auth0 and delete him
• if [email protected] has no "m" as a prefix
• if [email protected] has no roles assigned
• if testnewuser@ does not exist.

Cypress Guidelines

All tests in cypress/integrations should be found and can be directly executed. When writing tests, try to follow these guidelines if possible:

• Avoid any duplication of helper functions across several files! If testing the same page in several test suites (files), there's a tendency to copy-paste the whole file and then rewrite tests. This leads to code duplication of helper functions. Instead, helper functions needed in several locations should be defined in one of cypress/support files - then they're available globally. Find the matching one by name or create a new one. In latter case, don't forget to import it in cypress/integrations/index.js. Avoid creating miscellaneous file names as it tends to lead to chaos.
• Local helper functions defined in test files should have functional and easy-to-understand rather than technical names. Meaning, clickNewUserButton() is better than clickElementByTypeAndTestId('button','new-user-button').
• More general use helpers like 'clickElementByTypeAndTestId' can be used within the local helper functions if preferred. The reason for functional naming preference lies in increased readability of tests.
• Current codebase doesn't 100% follow everything stated above but it'd definitely help organising the test helpers accordingly from now on.

Known Cypress Issues

We experienced before that tests can fail in CircleCI, but not in the local environment. The main reason for it is that Cypress is usually executing the commands slower in a local dev environment. Therefore, a few additional guidelines when writing test:

• When you want to execute a redirect, e.g. example by clicking a button or tab, please add an assertion after the click, e.g. of the url cy.url().should('include', 'people_deactivated'). Due to this assertion cypress will definitely wait until the redirect is executed.
• Only if you use cy.visit() you can be sure that the cypress test wait until a page is fully loaded. Therefore, try to navigate as much as possible with cy.visit().

Notes for setting up an Auth0 tenant

If you are setting up a new Auth0 tenant, we require access to the Auth0 Management API. In order to do this

• Under 'APIs' select Auth0 Management API, go to 'Machine to Machine Applications' and enable access
• Grant scopes for read/update/delete/create users and users_app_metadata.

Contribution guidelines

You gotta be awesome and kind. For everything else, please see our contribution guidelines

Who do I talk to?

Drop us an email to [email protected]!

License

See the LICENSE file for license rights and limitations (Apache 2.0).