CoopCycle

CoopCycle is a self-hosted platform to order meals in your neighborhood and get them delivered by bike couriers. The only difference with proprietary platforms as Deliveroo or UberEats is that this software is reserved to co-ops.

The main idea is to decentralize this kind of service and to allow couriers to own the platform they are working for.
In each city, couriers are encouraged to organize into co-ops, and to run their very own version of the software.

The software is under active development. If you would like to contribute we will be happy to hear from you! All instructions are in the Contribute file.

Coopcycle-web is the main repo, containing the web API, the front-end for the website and the dispatch algorithm : Technical Overview. You can see it in action & test it here : https://demo.coopcycle.org

You can find a comprehensive list of our repos here : Our repos comprehensive list.

How to run a local instance

Please find below the steps to install the platform locally. You can find additional tips & configurations in the wiki.

Prerequisites

Install Docker and Docker Compose.

OSX

Use Docker for Mac which will provide you both docker and docker-compose.

Windows

Use Docker for Windows which will provide you both docker and docker-compose.
Depending on your platform, Docker could be installed as Native or you have to install Docker toolbox which use VirtualBox instead of Hyper-V causing a lot a differences in implementations.
If you have the luck to have a CPU that supports native Docker you can share your hard disk as a virtual volume for your appliances.

Docker doesn't work under Windows, you need to install linux in hypervisualization. Follow the recommendations here to activate the necessary features under windows 11 and make sure you have an administrator account
https://docs.docker.com/desktop/troubleshoot/topics/

Download docker
https://www.docker.com/products/docker-desktop/
Check in the BIOS that :
-hypervisualization (HYPER-V)
-Data Execution Prevention (DEP).
You can also use the following procedure for DEP:
Windows + r
Search for sysdm.cpl
Advanced system settings
In Performance, select settings data execution prevention "enable for all except those I select...". click on apply

install, from your PowerShell WSL 2 terminal
https://learn.microsoft.com/en-us/windows/wsl/install

configure your WSL 2 environment by creating a Linux administrator account. The password is not displayed (this is normal), so remember it.
https://learn.microsoft.com/fr-fr/windows/wsl/setup/environment#file-storage

Linux

Follow the instructions for your distribution. docker-compose binary is to be installed independently.
Make sure:

• to install docker-compose following instructions to get the latest version.
• to follow the post-installation steps.

Setup OpenStreetMap geocoders (optional)

CoopCycle uses OpenStreetMap to geocode addresses and provide autocomplete features.

Address autocomplete

To configure address autocomplete, choose a provider below, grab the credentials, and configure environment variables accordingly.

LOCATIONIQ_ACCESS_TOKEN
GEOCODE_EARTH_API_KEY

• For Geocode Earth, set COOPCYCLE_AUTOCOMPLETE_ADAPTER=geocode-earth
• For LocationIQ, set COOPCYCLE_AUTOCOMPLETE_ADAPTER=locationiq

Geocoding

To configure geocoding, create an account on OpenCage, and configure the OPENCAGE_API_KEY environement variable.

Run the application

Pull the Docker containers (optional)

We have prebuilt some images and uploaded them to Docker Hub.
To avoid building those images locally, you can pull them first.

docker compose pull

Populate your local .env and .env.test.local files:

cp .env.dist .env
touch .env.test.local

You only need to override the desired env vars at .env.test.local, like setting your GEOCODE_EARTH_API_KEY=...

Start the Docker containers

Minimum configuration:

docker compose up

With Storybook:

docker compose --profile devFrontend up

With Odoo:

docker compose --profile devOdoo up

At this step, the platform should be up & running, but the database is still empty.
To create the schema & initialize the platform with demo data, run:

make install

Open the platform in your browser

open http://localhost

Testing

Create the test database

docker compose run php bin/console doctrine:schema:create --env=test

Launch the PHPUnit tests

All Tests:

make phpunit

One package/test:

For example, to run only the tests in the AppBundle\Sylius\OrderProcessing folder:

make phpunit ARGS="/var/www/html/tests/AppBundle/Sylius/OrderProcessing"

See more command line options here.

Launch the Behat tests

All Tests:

make behat

One package/test:

To run only the tests with the @only tag:

make behat-only

To run only the tests in the features/authentication.feature file:

make behat ARGS="features/authentication.feature"

To only show errors in logs:

make behat ARGS="features/authentication.feature --no-snippets --format progress"

See more command line options here.

Launch the Jest tests

make jest

or to run only one test file:

make jest ARGS="js/app/api/__tests__/util.test.js"

Launch the Cypress tests

Cypress is a JS program for end-to-end testing and integration testing of components. Cypress itself runs on your own machine, and drives the app served by the nginx_test container, in the test environment, on http://localhost:9080 (this is the baseUrl in cypress.config.js).

1. Configure the API keys

In the .env file you need to set GEOCODE_EARTH_API_KEY to a valid API key. You need also Stripe configured on the platform or in the .env file (STRIPE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY, STRIPE_CONNECT_CLIENT_ID).

cypress.config.js loads .env and exposes it to the tests, so a missing key here shows up as a failing test, not as a configuration error.

2. Install Cypress

make cypress-install

This runs npm install and npx cypress install. The second one downloads the Cypress binary itself, which npm install skips when the binary is already cached or when CYPRESS_INSTALL_BINARY=0 is set. You can check what you have with npx cypress version: both "package version" and "binary version" must be filled in.

3. Prepare the test environment

# Create the schema of the test database
docker compose exec -T php bin/console doctrine:schema:create --env=test

# Install typesense for the test env (automatically done with `make install` or `make setup`)
docker compose exec -T php bin/console typesense:create --env=test

# Load the base data (countries, tax rates, …)
docker compose exec -T php bin/console coopcycle:setup --env=test

These are the same steps the CI runs before starting Cypress, see .github/workflows/test_e2e.yml.

Each spec loads its own fixtures (cy.loadFixtures() / cy.loadFixturesWithSetup()), which purge the database first, so you don't need to reset anything between runs.

4. Run the tests

# Open the Cypress GUI
make cypress-open

# Run the whole suite headlessly, like the CI does
make cypress

# Run a single spec
make cypress-only TESTFILE=pricing/setup_simple_km_based_pricing_rule.cy.js

# Run a single spec in a loop, until it fails (useful to hunt flaky tests)
make cypress-only-until-fail TESTFILE=pricing/setup_simple_km_based_pricing_rule.cy.js

The Cypress tests will run automatically in Github CI on the master branch. You can get screenshots of the failed tests from the Upload images for failed test step (there is a link there to download the failed steps).

Troubleshooting

If every test fails on cy.visit('/login') with a 500: Internal Server Error, check the permissions of the session directory. In the test environment sessions are written to var/cache/test/sessions, and PHP-FPM (running as www-data) cannot write there if the directory was created by a console command running as root:

docker compose exec php ls -ld var/cache/test/sessions
docker compose exec php sh -c 'chgrp -R www-data var/cache/test/sessions && chmod -R g+w var/cache/test/sessions'

If a test that calls cy.consumeMessages() fails because an asynchronous side effect never happened (an order price that is not recalculated, an import that stays pending…), the php_worker container is running in the wrong environment. MESSENGER_TRANSPORT_DSN is the same for dev and test, so both environments consume from the same Redis stream, in the same consumer group. By default php_worker runs messenger:consume async --env=dev, so it picks up messages dispatched by the tests and handles them against the dev database — the test then waits for a side effect that happened somewhere else.

The CI does not have this problem, because it exports APP_ENV=test for the whole job. Do the same locally before running these tests:

APP_ENV=test docker compose up -d php_worker

and put it back afterwards with docker compose up -d php_worker.

Note that stopping php_worker altogether is not enough: cy.consumeMessages() only runs messenger:consume for a few seconds, and messages are dispatched at the end of the HTTP request, so the test's own consumer regularly misses them. The specs rely on a worker being there.

Run linters (PHPStan)

docker compose exec php php vendor/bin/phpstan analyse -v

Debugging

1. Install and enable xdebug in the php container

make enable-xdebug

Note: If you've been working with this stack before you'll need to rebuild the php image for this command to work:

docker compose build php
docker compose restart php nginx

2. Enable php debug in VSCode

1. Install a PHP Debug extension, this is tested with felixfbecker.php-debug extension.
2. Add the following configuration in your .vscode/launch.json of your workspace:

{
	"configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9001,
      "pathMappings": {
          "/var/www/html": "${workspaceFolder}"
      },
      "xdebugSettings": {
          "max_data": 65535,
          "show_hidden": 1,
          "max_children": 100,
          "max_depth": 5
      }
    }
  ]
}

3. If you're having issues connecting the debugger yo can restart nginx and php containers to reload the xdebug extension.

docker compose restart php nginx

Running migrations

When pulling change from the remote, the database models may have changed. To apply the changes, you will need to run a database migration.

make migrations-migrate

License

The code is licensed under the Coopyleft License, meaning you can use this software provided:

• You are matching with the social and common company’s criteria as define by their national law, or by the European Commission in its October 25th, 2011 communication, or by default by the Article 1 of the French law n°2014-856 of July 31st, 2014 “relative à l’économie sociale et solidaire”
• You are using a cooperative model in which workers are employees