Skip to main content

Setting up our development environment

We provide and environment for both Linux and MacOS.

What you'll need

  • Git

  • mkcert

  • Docker version 20 or above and Docker compose version 2.1 or above:

    • Check your docker version using docker -v ;
    • Check your docker-component version using docker-compose -v ;

docker-compose is now included in docker engine, but our scripts still need docker-compose command.

Check if a version corresponds to your environment on this page: Run following commands (ajusting first url if needed):

curl -L > docker-compose
sudo mv docker-compose /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo chown root: /usr/local/bin/docker-compose
  • If you are using MacOS we recommend using Docker Desktop on Mac.

  • Python version 3.9 or above, pipenv and Fabric 2.7 or above:

    • Check your python version using python -V.
    • Check your pipenv version using pipenv --version.
  • Node.js version 18 and yarn package manager version 1.x:

    • Check your NodeJS version using node -v.
    • Check your yarn version using yarn -v.
If you have node version above 18

When you build front for the first time you will have an error like that Error: error:0308010C:digital envelope routines::unsupported

On Unix-like (Linux, macOS, etc..) set this env: export NODE_OPTIONS=--openssl-legacy-provider

For developers using MacOS we use the Symfony CLI for a better & faster Developer Experience. That's why we require MacOS users to install some PHP dependencies on the host, instead of using our docker container directly.

  • PHP version 7.4 and composer version 2.1 or above and Symfony CLI version 5.x or above:
    • Check your PHP version using php -v.
    • The following PHP extensions must be installed and enabled redis, imagick, amqp.
    • Check your composer version using composer --version.
    • Check you Symfony CLI version using symfony -V.
If you try to install php 7.4 with brew the formula is no longer available, instead run:
brew tap shivammathur/php && brew install shivammathur/php/php@7.4 && brew link php@7.4

Getting started

1. Clone the repository:

git clone
cd cap-collectif

2. Using our development CLI

Cap Collectif is a huge repository using a complex infrastructure with many technologies. In order to unify as much as possible our development experience between CI, Linux and MacOS, we implemented a CLI to simplify our interactions with Docker containers.

To run the CLI, you need to activate the Pipenv shell:

pipenv install # install dependencies from Pipfile
pipenv shell # activate this project's virtualenv

You can run several Fabric tasks such as:


This task will dump the version of every dependency that you need ton install on your host.


In order to list every available tasks you can use fab -l local.

3. Setup your environment variables

We use a lot of environment variables !

You need to generate a default .env.local file that contains the required variables to launch the repository:


This file is not versioned so you can update it freely.


To enable some services (like geolocation with Google Map) you will need to insert some credentials instead of INSERT_A_REAL_SECRET values in your .env.local file.

See environment variables documentation.

4. Setup DNS and SSL

The development environment is only accessible via HTTPS and the following hostnames:, capco.test and

That's why you need to setup some virtual hosts:

fab local.system.configure-vhosts

This task will automatically update your /etc/hosts file.

fab local.system.generate-ssl

This task will generate all SSL certificates you need on your host machine.

5. Build and launch our docker infrastructure

It's time to build and run our docker containers !

First build the docker cache and launch all the docker containers:

fab local.infrastructures.up

The first time you run those tasks, it will take quite some time… You may want a coffee break ?

6. Install code dependencies

You can run this task:


For MacOS users, it's faster to run all those tasks on your host:

yarn install --purelockfile
COMPOSER_MEMORY_LIMIT=-1 composer install
php bin/console assets:install public --symlink

7. Add some development data

It's time to add some data !

The following task will create the database, setup the SQL schema, add some fixtures and populate our search indexes:

fab local.database.generate

Use this task, every time you want to reset your database or take a fresh start.

8. Setup the frontend

First, install dependencies:

yarn install

Then, download the up to date translation files:

yarn trad

Only Cap Collectif employees can add new translations right now.

Before we can build our JS bundle, we need to generate some not committed files, run the compiler with:

yarn build-relay-schema

Our frontend code use Relay which requires a compiling step that read our *.graphql and *.js files to create some __generated__ directories and *.graphql.js files.

Finally we can run Webpack to build our JS bundle:

yarn build:prod

9. Setup the MacOS http proxy

For MacOS users only:

The fab local.infrastructures.up launch the Symfony CLI proxy.

But you need and extra step to make sure every requests to goes through the Symfony CLI proxy.

Run this command in a tab (you will need to keep it running):

cd infrastructure; python -m http.server 80

It will start a simple HTTP server to expose a proxy.pac file, that we will use to proxy the requests.

Update your proxys configuration (under "Network") with "Proxy auto config" and value http://localhost/proxy.pac.


Make sur to update your proxys configuration for both Wifi and LAN.

Some browsers require extra work

For Google chrome users, go to chrome://net-internals/#proxy, click Re-apply settings to apply the proxy.

10. Configure AC in your browser

In Firefox:

  • Go to about:preferences#privacy
  • Search for "certificates"
  • Click "View Certificates..."
  • In the Certificate Manager, click the Authorities tab
  • Click the "Import" button to import your certificate
    • Select ~/.local/share/mkcert/rootCA.pem file
    • You might be prompted to set the trust level upon importing the certificate. Select identify websites.
  • Restart Firefox

11. Open your first page

It's time to open your browser with:

It should work !

In the next steps of this tutorial, we are going to explain how to work with every part of the stack.