keycloak-development

Files (2)

• SKILL.md
• docker-compose-wrapper.sh · scripts/

SKILL.md (first lines)

# Keycloak Development

## Important Rules You MUST Follow

- Follow the commands and instructions carefully, unless you are asked to do otherwise, or you have specific reason to do otherwise.
- Always search the documentation before diverging from the instructions.
- Assume Keycloak is already running; check for it or start it only when explicitly asked to do so.
- Infer names and IDs from the context when possible. For example, if a realm name is required and there is only one realm, infer that realm name. If there are multiple realms, ask for clarification or use `master` as default.
- Use `http://keycloak.127-0-0-1.nip.io:8080` as the default base URL for API requests if the user has not specified a different URL for Keycloak.
- Replace `<ADMIN_TOKEN>` with the actual token value obtained from the token endpoint using command `$(curl -s -X POST http://keycloak.127-0-0-1.nip.io:8080/realms/master/protocol/openid-connect/token -d 'username=admin&password=admin&grant_type=password&client_id=admin-cli' | jq -r .access_token)`.
- Maven/mvnd builds produce huge output. Run builds under `runagent` and use `runagent wait` to block until completion, then check the tail of the log:
  ```bash
  runagent run -n build -- mvnd clean install ...; runagent wait build; runagent logs build --last 20
  ```

## Building Keycloak

### Full Build
```bash
runagent run -n build -- mvnd clean install -DskipTestsuite -DskipExamples -DskipTests; runagent wait build; runagent logs build --last 20 # Parallel build with mvnd (faster)
runagent run -n build -- mvn clean install -DskipTestsuite -DskipExamples -DskipTests; runagent wait build; runagent logs build --last 20 # Regular maven build (slower but use if you have issues with mvnd)
```

Always use `-DskipTests`, not `-Dmaven.test.skip=true`. `-Dmaven.test.skip=true` skips test compilation, which also skips producing test-jars that some modules depend on.

When switching between commits or branches, stop the mvnd daemon before rebuilding to avoid stale classloader state:
```bash
mvnd --stop
```

Note: `clean` wipes `quarkus/server/target/kc/data/` which contains:
- `h2/` — H2 database files (when using `--db=dev-file` or default)
- `password-blacklists/` — password denylist bloom files
- `log/` — HTTP access logs
- `import/` — realm import files

### Extracted Distribution
Full build produces `quarkus/dist/target/keycloak-*.tar.gz`. Extract once to get `kc.sh` and client tools (`kcadm.sh`, `kcreg.sh`) for use alongside quarkus:dev:

```bash
mkdir -p /tmp/keycloak-dev-dist
tar xzf quarkus/dist/target/keycloak-*.tar.gz -C /tmp/keycloak-dev-dist --strip-components=1
```

Examples:
```bash
/tmp/keycloak-dev-dist/bin/kc.sh tools build-password-denylist /path/to/denylist.txt
/tmp/keycloak-dev-dist/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin
```

## Running Keycloak on Command Line

### Development Mode
```bash
runagent delete keycloak >/dev/null 2>&1
runagent run -n keycloak -- ./mvnw -f quarkus/server/pom.xml compile quarkus:dev \
  -Dkc.config.built=true -Dquarkus.args="start-dev --db=dev-mem" \
  -Dkc.bootstrap-admin-username=admin -Dkc.bootstrap-admin-password=admin
for i in $(seq 1 90); do curl -s -o /dev/null -m 2 http://localhost:8080/realms/master 2>/dev/null && { echo "ready after ${i}s"; break; }; sleep 1; done
```

With PostgreSQL (requires running docker compose with PostgreSQL container):
```bash
runagent delete keycloak >/dev/null 2>&1
runagent run -n keycloak -- ./mvnw -f quarkus/server/pom.xml compile quarkus:dev \
  -Dkc.config.built=true \
  -Dquarkus.args="start-dev -Dkc.db=postgres -Dkc.db-url=jdbc:postgresql://localhost/keycloak -Dkc.db-username=keycloak -Dkc.db-password=keycloak" \
  -Dkc.bootstrap-admin-username=admin -Dkc.bootstrap-admin-password=admin
for i in $(seq 1 90); do curl -s -o /dev/null -m 2 http://localhost:8080/realms/master 2>/dev/null && { echo "ready after ${i}s"; break; }; sleep 1; done
```

### Per-Category Debug Logging
```bash
runagent delete keycloak >/dev/null 2>&1
runagent run -n keycloak -- ./mvnw -f quarkus/server/pom.xml compile quarkus:dev \
  -Dkc.config.built=true \
  '-Dquarkus.args=start-dev --db=dev-mem --log-level=org.keycloak.services.resources.admin.AdminRoot:debug,org.keycloak.services.managers.AuthenticationManager:debug' \
  -Dkc.bootstrap-admin-username=admin -Dkc.bootstrap-admin-password=admin
for i in $(seq 1 90); do curl -s -o /dev/null -m 2 http://localhost:8080/realms/master 2>/dev/null && { echo "ready after ${i}s"; break; }; sleep 1; done
```

The `--log-level` flag accepts comma-separated `category:level` pairs. This enables DEBUG for specific classes without the noise of global debug logging.

## Debugging in VS Code

### Prepare VS Code Configuration

```bash
mkdir -p .vscode
cat > .vscode/launch.json <<EOF
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "Debug Quarkus (keycloak-junit5)",
            "request": "launch",
            "mainClass": "org.keycloak.Keycloak",
            "projectName": "keycloak-junit5",

            "args": "start-dev --verbose",

            // All configuration options:
            // - https://www.keycloak.org/server/all-config
            "env": {
                "KC_HOSTNAME": "keycloak.127.0.0.1.nip.io",
                "KC_BOOTSTRAP_ADMIN_USERNAME": "admin",
                "KC_BOOTSTRAP_ADMIN_PASSWORD": "admin",
                "KC_DB_URL": "jdbc:h2:./quarkus/dist/target/keycloakdb;NON_KEYWORDS=VALUE;AUTO_SERVER=TRUE",
                // "KC_DB_URL": "jdbc:postgresql://localhost:5432/keycloak",
                // "KC_DB_USERNAME": "keycloak",
                // "KC_DB_PASSWORD": "keycloak",
            },
        },
    ]
}
EOF

cat > .vscode/settings.json <<EOF

From tsaarni/agent-skills, Apache-2.0.

More from tsaarni/agent-skills