Getting started

This guide covers setting up the LiturgicalCalendar project for local development.

Prerequisites

• PHP 8.4+ with the following extensions: intl, zip, calendar, yaml, gettext
• Composer for dependency management
• Docker and Docker Compose (optional, for infrastructure services)
• PostgreSQL (optional, only needed for RBAC/authentication features — or use the Docker stack)

API setup

Clone and install

git clone https://github.com/Liturgical-Calendar/LiturgicalCalendarAPI.git
cd LiturgicalCalendarAPI
composer install

Environment configuration

Copy the example environment file and adjust as needed:

cp .env.example .env.local

The key variables for local development are:

• API_PROTOCOL, API_HOST, API_PORT — where the API server listens (defaults: http, localhost, 8000)
• APP_ENV — set to development
• JWT_SECRET — for authentication (a default is provided for development)

See .env.example for the full list of configuration options with documentation.

Running the API server

The API requires a multi-worker setup (6 workers) using PHP's built-in server:

composer start    # Starts the server on localhost:8000
composer stop     # Stops the server

Alternatively, use the shell script directly:

./start-server.sh

If using VS Code, you can start the server via Ctrl+Shift+B (the project includes a tasks.json configuration).

Infrastructure services (Docker Compose)

The docker-compose.yml in the API repository provides the supporting infrastructure services. These are not required for basic API development, but are needed when working on authentication and RBAC features:

• Zitadel — OIDC identity provider
• Login V2 — Zitadel login UI
• OpenFGA — fine-grained authorization
• PostgreSQL — database
• Mailpit — email testing
• Adminer — database UI

The setup involves several steps:

1. Start the containers:

   docker compose up -d

2. Configure the Zitadel project (create project, roles, and applications) via the Zitadel Console at http://localhost:8080/ui/console. See infrastructure/README.md for the detailed steps.

3. Run the OpenFGA setup script:

   ./scripts/setup-openfga.sh --update-env

4. Update .env.local with the Zitadel client IDs, project ID, and database credentials from the previous steps.

5. Restart the containers to pick up the new environment variables:

   docker compose down && docker compose up -d

The API itself still runs natively via composer start — the Docker stack only provides the services the API connects to. See infrastructure/README.md for the full setup walkthrough, port assignments, and troubleshooting.

Frontend setup

The frontend is a separate repository with two setup options.

Option A: Native PHP (alongside the API)

git clone https://github.com/Liturgical-Calendar/LiturgicalCalendarFrontend.git
cd LiturgicalCalendarFrontend
composer install
cp .env.example .env.development

Start the frontend development server (ensure the API is running first):

php -S localhost:3000

Option B: Full-stack Docker Compose

The frontend repository has its own docker-compose.yml that orchestrates the entire stack — API, frontend, test interface, and all infrastructure services — without requiring a local PHP installation:

git clone https://github.com/Liturgical-Calendar/LiturgicalCalendarFrontend.git
cd LiturgicalCalendarFrontend
docker compose up -d

See the Frontend README for details on the full-stack Docker setup.

Running tests

# Run all tests (requires the API server to be running for integration tests)
composer test

# Run only fast unit tests (no server needed)
composer test:quick

# Run a single test file
vendor/bin/phpunit phpunit_tests/Services/RateLimiterTest.php

See How to write unit tests for details on the test infrastructure.

Code quality

composer lint          # Check code style (phpcs, PSR-12)
composer lint:fix      # Auto-fix code style
composer analyse       # PHPStan static analysis (level 10)
composer parallel-lint # PHP syntax checking
composer lint:md       # Markdown linting

WebSocket test server

The liturgical event test interface uses a WebSocket server:

composer ws:start    # Start the WebSocket test server
composer ws:stop     # Stop the WebSocket test server

See Unit Test server and interface for details.

Further reading

• API README — full project description, data sources, and characteristics
• Infrastructure README — Docker Compose infrastructure details and troubleshooting
• Source data — how the liturgical calendar source data is organized
• Translating — contributing translations via Weblate

---

For Contributors: Source data Next → | Home