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 is automated via two scripts:

# Start Docker stack, configure Zitadel (project, roles, OIDC apps),
# and update .env files automatically:
./scripts/setup-zitadel.sh --docker-init --update-env

# Create the OpenFGA store, load the authorization model,
# and update .env files with store/model IDs:
./scripts/setup-openfga.sh --update-env

The Zitadel script handles creating the project, roles (admin, developer, calendar_editor, test_editor), OIDC applications, service accounts, and writing all credentials to the relevant .env files. It also restarts app containers if they exist in the compose stack to pick up the new environment variables.

Both scripts use --update-env to automatically write credentials to your environment files. They look for files in priority order: .env.local, .env.development, .env — and update whichever one exists. The Zitadel script also writes Docker Compose variables to the root .env file (used by docker-compose.yml for service configuration). Additionally, both scripts discover sibling project directories (Frontend, UnitTestInterface) and update their .env files as well.

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