Zitadel Infrastructure Setup - Liturgical-Calendar/LiturgicalCalendarAPI GitHub Wiki

This page covers how to set up the Zitadel infrastructure for local development.

• Docker and Docker Compose
• The LiturgicalCalendarAPI repository cloned (the docker-compose.yml and infrastructure/ directory are in the repo root)

From the LiturgicalCalendarAPI directory:

docker compose up -d

This starts the following services:

After the services are up, create the OpenFGA store and load the authorization model (see OpenFGA Fine-Grained Authorization):

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

After the services are running, configure the Zitadel project:

Open http://localhost:8080/ui/console and log in with the default admin credentials:

• Username: [email protected]
• Password: RootPassword1!

Create a project named "LiturgicalCalendar".

In the project, create these roles:

API Application (Machine-to-Machine):

• Name: "LiturgicalCalendar API"
• Type: API
• Auth Method: Private Key JWT or Client Credentials
• Generate a Personal Access Token (PAT) for ZITADEL_MACHINE_TOKEN

Frontend Application (Web with PKCE):

• Name: "LiturgicalCalendar Frontend"
• Type: Web
• Auth Method: PKCE
• Redirect URIs:
  • http://localhost:3000/auth/callback (development)
  • https://your-production-domain.com/auth/callback (production)
• Post Logout URIs:
  • http://localhost:3000 (development)
  • https://your-production-domain.com (production)

In Organization Settings > Login Behavior:

• Enable self-registration
• Configure email verification

Copy the client IDs from the applications you created and update your API .env.local:

ZITADEL_ISSUER=http://localhost:8080
ZITADEL_CLIENT_ID=<frontend-client-id>
ZITADEL_PROJECT_ID=<project-id>
ZITADEL_MACHINE_TOKEN=<machine-user-pat>

DB_HOST=localhost
DB_PORT=5432
DB_NAME=litcal
DB_USER=litcal
DB_PASSWORD=litcal_secure_password

The scripts/init-db.sql script runs automatically on first PostgreSQL startup. It is bootstrap-only: it creates the database roles and databases (including the zitadel database managed entirely by Zitadel, the litcal application database, and the openfga database) and enables the pgcrypto extension for UUID generation.

The application schema (access requests, applications, API keys, outbox, audit log) is managed with Doctrine Migrations. Migration classes live in src/Migrations/. Apply them with:

composer db:migrate              # Apply pending migrations
composer db:migrations:status    # Show applied/pending versions

In deployed environments, migrations can also be applied through the operations endpoints (POST /_ops/migrate, GET /_ops/migrate/status).

# Start services
docker compose up -d

# Stop services
docker compose down

# View logs
docker compose logs -f zitadel
docker compose logs -f login
docker compose logs -f db

# Reset everything (WARNING: destroys all data)
docker compose down -v
docker compose up -d

# Connect to PostgreSQL as superuser
docker compose exec db psql -U postgres

# Connect to application database
docker compose exec db psql -U litcal -d litcal

# Check login names if you can't log in
docker compose exec db psql -U postgres -d zitadel -c "select * from projections.login_names3;"

Check if PostgreSQL is healthy:

docker compose ps
docker compose logs db

Check if Zitadel is healthy and the PAT was generated:

docker compose logs login

The Login V2 service uses network_mode: service:zitadel to share Zitadel's network, so it can reach Zitadel at localhost:8080 internally.

Ensure port 8080 is not in use by another service:

lsof -i :8080

Verify both databases were created:

docker compose exec db psql -U postgres -c '\l'

You should see both zitadel and litcal databases listed.

Authentication & RBAC: ← OpenFGA Fine-Grained Authorization | Home | Zitadel Production Deployment →