This guide walks through setting up a local Episciences development environment from scratch using Docker.

Verify your installation:

docker --version
docker compose version

The application uses virtual-host-based routing. Add the following line to /etc/hosts before starting the containers:

sudo sh -c 'echo "127.0.0.1 localhost dev.episciences.org oai-dev.episciences.org data-dev.episciences.org manager-dev.episciences.org" >> /etc/hosts'

Verify:

ping -c1 dev.episciences.org

DB (MySQL), Solr, Traefik, and phpMyAdmin are managed by episciences-infrastructure. Start it before this project:

cd ../episciences-infrastructure
make up          # creates epi-network, starts Traefik + DBs + Solr
make db-import   # first-time DB init (if volumes are empty)
make solr-setup  # first-time Solr collection setup

git clone <repository-url>
cd episciences
make dev-setup

make dev-setup performs the following steps automatically:

1. make build — builds all Docker images (Apache vhost, PHP-FPM, etc.)
2. make copy-config — copies config/dist-dev.pwd.json → config/pwd.json
3. make setup-logs — creates log directories with correct permissions
4. make up — starts all containers in detached mode
5. make wait-for-db — waits until MySQL is accepting connections
6. make init-data-dir — creates data/dev/ with sub-directories and seeds navigation.json
7. make composer-install — installs PHP dependencies
8. make load-dev-db — loads the development SQL dataset
9. make init-dev-users — creates 30 test users and prints a summary table
10. make create-bot-user — creates the fixed episciences-bot account
11. make collection — creates the Solr episciences collection
12. make index — indexes sample content into Solr

When it completes, open https://dev.episciences.org/ in your browser (accept the self-signed certificate warning).

# Start containers
make up

# Stop containers
make down

# Restart everything
make restart

# View logs
make logs
# Or for a specific container:
make logs CONTAINER=php-fpm

Episciences ships a Symfony Console application at scripts/console.php. All commands run inside the PHP container. Use make <target> as a shortcut during development, or invoke the script directly in production.

# List all available commands
docker compose exec -u www-data php php scripts/console.php list

# Get help for a specific command
docker compose exec -u www-data php php scripts/console.php enrichment:creators --help

Each command has a corresponding make target that runs it inside the container as www-data. Run make help or inspect the Makefile for the full list. Example:

make enrich-creators
make enrich-zb-reviews ARGS="--rvcode=jdmdh --dry-run"

In production there is no Make or Docker. Commands are run directly on the server:

sudo -u www-data php /var/www/htdocs/scripts/console.php enrichment:creators --rvcode=jdmdh

The project includes several tools to ensure code quality and maintainability.

Analyzes your code for potential bugs and type errors without running it.

# Run on the whole project
make phpstan

# Run on a specific file or directory
make phpstan TARGET=library/Episciences/Api

Helps with automated code upgrades and refactoring.

# Run in dry-run mode (see what would change)
make rector DRY_RUN=1

# Apply changes
make rector

Generates a comprehensive HTML report about code complexity, coupling, and maintainability.

# Optional: Run PHP tests first to include assertions count in the report
make test-php

# Generate/Update the report
make phpmetrics

The report is generated in phpmetrics/report/index.html. Open it in your browser to view the dashboard.

The project uses PHPUnit for backend tests and Jest for frontend tests.

# Run all tests (PHP + JS)
make test

# Run all tests with coverage reports
make test-coverage

# Run only PHP tests
make test-php

# Run only JS tests
make test-js

PHP coverage is generated in build/coverage (if Xdebug/PCOV is available). JS coverage is generated in coverage/lcov-report/index.html.

All HTTPS services use Traefik's self-signed certificate — accept the browser warning on first access.

The terminal prints a table of all generated usernames after make init-dev-users completes. Users are distributed as: 1 Chief Editor, 2 Administrators, 5 Editors, 22 Members.

If you see a permission-denied error during composer-install, your host UID does not match the container's expected 1000:1000. Override it:

make dev-setup CNTR_USER_ID=0:0

Or, to run only composer as root without redoing the full setup:

make composer-install CNTR_USER_ID=0:0

The application needs data/dev/config/navigation.json to bootstrap. This is created automatically by make init-data-dir (which is part of make dev-setup). If you skipped it or the directory was deleted, run:

make init-data-dir

This requires the containers to be running (make up first).

make copy-config asks for confirmation interactively when config/pwd.json already exists. In non-interactive environments, pre-create the file before running make dev-setup:

cp config/dist-dev.pwd.json config/pwd.json
make dev-setup

After make init-dev-users runs, a table listing every username, role, and email is printed to stdout. If you missed it, you can re-run the command alone:

make init-dev-users

Note: this will attempt to create users again; duplicate-email errors are reported but do not break the existing accounts.

To start over with a clean database:

make down
make clean-mysql    # WARNING: deletes all MySQL volumes — prompts for confirmation
make dev-setup