Document WithRealmImport production limitation and alternatives

[Copilot]

Documentation Update for Keycloak WithRealmImport() Limitation

• Explore repository and locate Keycloak documentation file
• Review current documentation structure
• Add production limitation note to WithRealmImport() section
• Add production alternatives section with three approaches
• Build and verify documentation changes
• Take screenshots of updated documentation
• Clean up unrelated file changes
• Address code review feedback
• Add note about using specific version tags instead of latest
• Final verification

Changes Made

Updated /src/frontend/src/content/docs/integrations/security/keycloak.mdx to:

1. Added Caution callout explicitly stating that WithRealmImport() is not supported in production deployments (such as when using aspire deploy) because it relies on mounting local directories as volumes

2. Added Production alternatives section with three complete, actionable approaches:

   • Custom Keycloak image: Build a container image with realm JSON files baked in, with clear instructions on configuring startup arguments in AppHost
   • Initialization service: Use Keycloak Admin REST API or Admin Client to programmatically configure realms
   • Infrastructure as Code: Use Terraform with the Keycloak provider

3. Added note about version pinning: Added an Aside note recommending to replace latest with a specific Keycloak version tag (e.g., 25.0.0) or image digest for production to ensure reproducible builds and avoid unexpected changes

Each alternative includes complete code examples with proper configuration and links to relevant documentation.

Resolves

This PR addresses the issue where developers spend hours trying to get WithRealmImport() working in production without realizing it's not supported. The updated documentation now clearly states this limitation upfront and provides practical alternatives.

Screenshots

Caution message:

Production alternatives with version note:

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Missing Keycloak documentation regarding realm imports in production</issue_title>
<issue_description>After spending 4 hours attempting to get WithRealmImport() to work when running aspire deploy, @davidfowl informed that it's not supported in production. The documentation does not state this anywhere.

Fowler and I agreed that this should be explicitly stated, and most probably in the section specifically regarding Realm importing:
https://aspire.dev/integrations/security/keycloak/#add-keycloak-resource-with-realm-import

It would also be nice if the documentation suggested alternatives on how to seed Keycloak (i.e. service or baking realm JSON into image).</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Missing Keycloak documentation regarding realm imports in production #375

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[IEvangelist]

Hey @pfo-omicsstudio, please have a look at this. Does it make sense, is it accurate?

[Copilot]

Pull request overview

This pull request addresses a critical documentation gap by documenting that the WithRealmImport() method is for local development only and does not work in production deployments. The PR adds a caution callout and provides three practical production alternatives with code examples, helping developers avoid spending hours debugging a limitation that wasn't previously documented.

Changes:

• Added a caution callout explaining that WithRealmImport() is development-only due to volume mounting constraints
• Added a "Production alternatives for realm seeding" subsection with three approaches (custom Keycloak image, initialization service, and Infrastructure as Code)
• Included code examples and external documentation links for each alternative

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The Dockerfile example uses FROM quay.io/keycloak/keycloak:latest, which pins your Keycloak base image to the mutable latest tag and introduces a supply-chain risk if that image is compromised or changes unexpectedly. An attacker who compromises or replaces the latest tag in the remote registry could affect your builds or running containers without any change on your side. Use a specific, trusted Keycloak version tag or image digest for the base image to ensure reproducible and auditable builds.

[pfo-omicsstudio]

Hey @pfo-omicsstudio, please have a look at this. Does it make sense, is it accurate?

Yeah, that's pretty great! Might be worth mentioning that bind volumes in general are not supported in prod? Unsure, but Fowler mentioned that to me in the Discord, and I found that insight pretty valuable.

Also, one question I would have after reading this - what about future versions? Is it always going to be like this, or are there plans for supporting it in the future? Maybe a short sentence or two addressing this.

[pfo-omicsstudio]

I also noticed the AddKeycloak method configures a bunch of defaults for the resource, so the sample code:

var keycloak = builder.AddContainer("keycloak", "your-registry/keycloak-with-realms", "latest")
    .WithHttpEndpoint(port: 8080, targetPort: 8080)
    .WithArgs("start", "--import-realm");

is a bit misleading, since it suggests an equivalent setup, but omits the defaults AddKeycloak applies (endpoints/env/health checks/etc.), so it's not actually the same configuration.

I know this is out of scope for this specific documentation issue, but being able to call AddKeycloak with a custom dockerfile would solve this.

EDIT:
OK my bad, you can actually do that, and I feel like the documentation should suggest that instead:

var keycloak = builder
    .AddKeycloak("keycloak", adminPassword: keycloakAdminPassword)
    .WithDockerfile("./keycloak");

with this directory layout:

├── AppHost.cs
...
├── keycloak
│   ├── Dockerfile
│   └── realms
│       └── demo-realm.json

and the same Dockerfile you already have.

[IEvangelist]

Hey @copilot, please address review feedback - for the latest tag, simply add a note.

[Copilot]

Hey @copilot, please address review feedback - for the latest tag, simply add a note.

Added a note after the Dockerfile example recommending to replace latest with a specific Keycloak version tag (e.g., 25.0.0) or image digest for production environments to ensure reproducible builds and avoid unexpected changes. (49983b1)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node /home/REDACTED/work/aspire.dev/aspire.dev/src/frontend/node_modules/.bin/../astro/astro.js dev (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[pfo-omicsstudio]

Hey @copilot, please address review feedback - for the latest tag, simply add a note.

I think you ought to take a closer look yourself...
Copilot did not address my feedback at all. It's still misleading.