Copy page

Backend

Docker Infrastructure and Casdoor Setup

Docker Infrastructure and Casdoor Setup

Relevant source files

The following files were used as context for generating this wiki page:

• infra/docker-compose.postgres.yml
• infra/init-db/01-create-casdoor-db.sql
• scripts/check-casdoor-db.ts
• scripts/fix-casdoor-admin.ts
• scripts/fix-missing-audit-records.ts
• scripts/setup-casdoor.ts
• src/modules/auth/avatar-svg-generator.ts
• src/modules/auth/config-repo.ts
• src/modules/auth/config.ts
• src/modules/customers/list-config.ts
• src/openapi/openapi.ts

This section describes the containerized infrastructure and the automated bootstrap process for the Identity Provider (IdP) integration. The Primebrick backend relies on a multi-service Docker stack and a specialized orchestration script to synchronize credentials between Casdoor and the local PostgreSQL instance.

1. Docker Services Overview

The local development environment is managed via infra/docker-compose.postgres.yml infra/docker-compose.postgres.yml:1-112. It defines three primary services and utilizes named volumes for persistence.

Service Definitions

Service	Image	Role	Persistence Volume
postgres	postgres:18-bookworm	Primary DB (Primebrick & Casdoor)	primebrick_pg18_data
casdoor	casbin/casdoor:3.75.0	OIDC Identity Provider	primebrick_casdoor_data
nats	nats:latest	Message Broker (JetStream enabled)	primebrick_nats_data

PostgreSQL Customization

The postgres service includes a custom entrypoint to install and enable pg_partman, which is required for database partitioning infra/docker-compose.postgres.yml:46-52. It binds to 127.0.0.1:${PG_HOST_PORT:-5432} to avoid port conflicts and IPv6 resolution issues on some host systems infra/docker-compose.postgres.yml:37-40.

Casdoor Database Initialization

Casdoor is configured to use the same PostgreSQL instance but targets a separate database named casdoor infra/docker-compose.postgres.yml:64-68. The casdoor database is created via the SQL script infra/init-db/01-create-casdoor-db.sql infra/init-db/01-create-casdoor-db.sql:1-3 and the Casdoor flag --createDatabase=true infra/docker-compose.postgres.yml:76.

Sources:

• infra/docker-compose.postgres.yml:1-112
• infra/init-db/01-create-casdoor-db.sql:1-3

---

2. Casdoor Bootstrap Logic (setup-casdoor.ts)

The scripts/setup-casdoor.ts script is a critical maintenance tool that ensures the Identity Provider is correctly configured for the Primebrick API. It bypasses common API limitations by performing direct SQL updates on the Casdoor internal tables before using the HTTP API for entity creation.

Execution Flow

1. Credential Discovery: It connects to the casdoor database and retrieves the client_id and client_secret for the internal app-built-in application scripts/setup-casdoor.ts:49-56. These are used to authenticate subsequent API calls.
2. SQL Patching: It updates the application table in the casdoor database to enable password, authorization_code, and client_credentials grant types for the primebrick-api application scripts/setup-casdoor.ts:44-47.
3. App Provisioning: If the primebrick-api application does not exist, it inserts it directly into the application table scripts/setup-casdoor.ts:82-88.
4. API Synchronization: It uses the discovered master credentials to call Casdoor's /api/add-organization and /api/add-user endpoints scripts/setup-casdoor.ts:131-138.
5. Local Sync: Finally, it creates a matching record in the Primebrick public.organizations table to ensure the local DB recognizes the IdP organization scripts/setup-casdoor.ts:141-160.

Natural Language to Code Entity Mapping: Casdoor Setup

The following diagram maps the logical setup steps to the specific functions and SQL operations in setup-casdoor.ts.

Code
graph TD
    subgraph "Natural Language Space"
        A["Bootstrap Casdoor"]
        B["Enable Grant Types"]
        C["Sync Org to API DB"]
    end

    subgraph "Code Entity Space"
        A --> |"calls"| F1["scripts/setup-casdoor.ts:main()"]
        F1 --> |"SQL UPDATE"| Q1["UPDATE application SET grant_types..."]
        B --> |"implemented in"| Q1
        F1 --> |"SQL INSERT"| Q2["INSERT INTO public.organizations"]
        C --> |"implemented in"| Q2
    end

Sources:

• scripts/setup-casdoor.ts:31-160
• src/modules/auth/config-repo.ts:23-47

---

3. Credential Consolidation and Auth Configuration

The system supports two authentication modes: STANDALONE and GATEWAY src/modules/auth/config.ts:4-15. Configuration is loaded via getAuthConfig, which prioritizes database settings over environment variables src/modules/auth/config.ts:93-110.

Auth Configuration Hierarchy

Setting	DB Key (auth_configurations)	Env Variable
Issuer URL	oidc_issuer_url	OIDC_ISSUER_URL
Client ID	oidc_client_id	OIDC_CLIENT_ID
Roles Path	N/A	AUTH_ROLES_PATH

The loadAuthConfigFromDb function in src/modules/auth/config-repo.ts src/modules/auth/config-repo.ts:23-47 fetches these values from the auth_configurations table. If the database is unavailable or the keys are missing, it falls back to defaults (e.g., http://localhost:8000 for Casdoor) src/modules/auth/config-repo.ts:34-40.

Sources:

• src/modules/auth/config.ts:1-157
• src/modules/auth/config-repo.ts:1-66

---

4. Maintenance and Fix Scripts

fix-missing-audit-records.ts

Because the initial bootstrap of the admin user and organization happens outside the standard API flow, they often lack audit trails. This script backfills the organizations_audit and user_profiles_audit tables scripts/fix-missing-audit-records.ts:7-113.

• Action: INSERT scripts/fix-missing-audit-records.ts:42
• Delta: Captures the initial state of fields like idp_code, email, and display_name scripts/fix-missing-audit-records.ts:46-52.

fix-casdoor-admin.ts

A utility to force-update the admin user in Casdoor. It ensures the user has isAdmin: true, isVerified: true, and emailVerified: true scripts/fix-casdoor-admin.ts:162-164. It attempts to locate the user using multiple ID formats: org/user, admin/user, and user scripts/fix-casdoor-admin.ts:84-88.

Infrastructure Component Interaction

The following diagram illustrates how the Docker services and setup scripts interact to establish the system state.

Code
sequenceDiagram
    participant D as Docker Compose
    participant S as setup-casdoor.ts
    participant C as Casdoor Container
    participant P as Postgres (casdoor DB)
    participant PB as Postgres (primebrick DB)

    D->>P: Initialize schema
    D->>C: Start service
    S->>P: Update 'app-built-in' grant_types
    S->>P: Provision 'primebrick-api' app
    S->>C: API: Create Organization (ACME)
    S->>C: API: Create Admin User
    S->>PB: INSERT INTO public.organizations
    Note over S,PB: Ensures IDP/API sync

Sources:

• scripts/fix-missing-audit-records.ts:1-126
• scripts/fix-casdoor-admin.ts:1-175
• infra/docker-compose.postgres.yml:76-85

---