# pm-keycloak

Keycloak deployment with declarative realm configuration via keycloak-config-cli.

## Stack

- **Keycloak 26.5.4** — identity and access management
- **PostgreSQL 16** — persistent storage
- **keycloak-config-cli 6.5.0** — declarative realm configuration

## Installation

### Prerequisites

- Docker and Docker Compose

### Setup

```bash
cd compose
cp .env.example .env
```

Edit `.env` with your credentials:

```env
COMPOSE_PROJECT_NAME=pm-keycloak
KC_DB_PASSWORD=<your-db-password>
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=<your-admin-password>
```

### Start

```bash
docker compose up -d
```

Keycloak is available at http://localhost:8080.

keycloak-config-cli runs once at startup, applies all realm configuration files, then exits. This is expected behavior.

## Configuration

Realm configuration files live in `compose/keycloak-config/`. Each `.yaml` file maps to one realm.

### Apply configuration changes

After editing a realm file:

```bash
docker compose run --rm keycloak-config-cli
```

### File structure

```
compose/keycloak-config/
├── master-realm.yaml   # minimal patch of the master realm
└── demo-realm.yaml     # example realm with roles and clients
```

### Managed mode

`IMPORT_MANAGED_REALM: full` is set, meaning keycloak-config-cli is the source of truth for each realm it manages. Anything not declared in a YAML file will be removed from Keycloak on the next apply.