Repository files navigation

You just found the Drop App (first version ofBoxtribute - 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 byBoxtribute 2.0.

Dropapp was initially developed forDrop In The Ocean - a Norwegian NGO who is working in three refugee camps throughout Greece. Other users includeSamos Volunteers,Europe Cares,Hermine,The Free Shop Lebanon,Intereuropean Human Aid Association (IHA) andMovement 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 atjointheteam@boxtribute.org! You can also check out ourwebsite for more details about the kind of help we need on this project.

• InstallDocker

• InstallPHP 8.2 or later.

• Ensure you have thembstring,curl,mysql andxdebug PHP extensions installed. On Ubuntu:

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

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/dropappchmod -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 | phpmv 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 checkdocs/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 seeddb/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 requesthttp://localhost:8100/cron/reseed-auth0.php

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

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

• some.admin@boxtribute.org (God User)

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

• dev_headofops@boxaid.org
• dev_coordinator@boxaid.org
• dev_volunteer@boxaid.org
• warehouse.volunteer@lesvos.org
• freeshop.volunteer@lesvos.org
• library.volunteer@lesvos.org

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

• dev_headofops@boxcare.org
• dev_coordinator@boxcare.org (Coordinator at bases Thessaloniki and Samos)
• dev_volunteer@boxcare.org (Volunteer at bases Thessaloniki and Samos)
• coordinator@thessaloniki.org
• coordinator@samos.org
• coordinator@athens.org
• volunteer@thessaloniki.
• volunteer@samos.org
• volunteer@athens.org
• warehouse.volunteer@athens.org
• freeshop.volunteer@athens.org
• label@athens.org (only for label creation)

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

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

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

If you're using VSCode, thevscode-php-cs-fixer extension will be suggested automatically and applyauto format on save.

Alternatively, you can run

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

in the root manually.

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

If you're using VS Code, if you install thePHP 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.

Docker containers running on linux cannot resolve the addresshost.docker.internal to an ip-address. To use Xdebug on linux you have to specify the internal ip-address of the docker container indocker-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 indocker-compose.yaml here:

    environment:        XDEBUG_CONFIG: remote_host=172.19.0.1

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 dbdropapp_dev isdropapp_root.

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

We're usingPhinx 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 indb/migrations. Please use this file to write your db migration.

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

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

If the tests 2.4 and 2.9 fail, check

• if the user withpauli@pauli.co exists in Auth0 and delete him
• ifadmin@admin.co has no "m" as a prefix
• ifadmin@admin.co has no roles assigned
• if testnewuser@ does not exist.

All tests incypress/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 ofcypress/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 incypress/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 thanclickElementByTypeAndTestId('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.

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 urlcy.url().should('include', 'people_deactivated'). Due to this assertion cypress will definitely wait until the redirect is executed.
• Only if you usecy.visit() you can be sure that the cypress test wait until a page is fully loaded. Therefore, try to navigate as much as possible withcy.visit().

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.

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

Drop us an email tohello@boxtribute.org!

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