Keycloak start vs start-dev: Development and Production Modes

In this article we will compare Keycloak start-dev and production start on the same 26.7.3 image.

start-dev starts Keycloak with development-friendly defaults such as HTTP, relaxed hostname handling, and local caching. start activates the production profile, where HTTP is disabled and hostname/TLS configuration is expected. Both commands can run the Keycloak build automatically when needed.

Keycloak start vs start-dev at a glance

Both commands launch the same Keycloak binary. The difference is which profile Keycloak applies. A profile is the set of default behaviors Keycloak uses for a particular mode. start-dev uses the development profile; start uses the production profile. Logs show this as Profile dev or Profile prod.

Both commands can automatically run kc.sh build. That is not the main difference between development and production mode.

Changing the command from start-dev to start does more than disable development conveniences. It activates the production profile, so settings that were optional in development (especially hostname and HTTPS) must now be configured appropriately.

What start-dev changes

start-dev turns on development conveniences so you can open the Admin Console without designing hostname, TLS, or clustering first. On Keycloak 26.7.3 the practical defaults include:

• HTTP enabled on port 8080 so http://127.0.0.1:8080/admin/ works on the container host
• Strict hostname resolution disabled so minor hostname mismatches during local testing do not block redirects
• Local cache for Infinispan instead of clustering-oriented defaults
• Theme and template caching reduced so theme edits show up quickly while you iterate

These defaults make it easier to test realms, clients, themes, and login flows locally without first configuring HTTPS or clustering. The server tells you plainly in the logs:

Running the server in development mode. DO NOT use this configuration in production.

Keycloak prints this warning because start-dev deliberately uses development-oriented defaults and should not be used for production deployments.

What changes when you use production start

Production start activates the prod profile. Keycloak then assumes you are publishing a real URL to users and browsers, not only opening localhost on the container host.

Production mode requires Keycloak to know how its public hostname should be resolved. The normal approach is to set KC_HOSTNAME (or hostname in keycloak.conf) to the name clients use in the browser. If your deployment intentionally uses dynamic hostname resolution, you can instead disable hostname strictness with hostname-strict=false.

You also need either HTTPS on Keycloak, or explicitly enabled HTTP when TLS terminates elsewhere.

Hostname v2 production rules require either --hostname or explicitly --hostname-strict=false.

For an actual production deployment, also use a supported production database rather than the embedded dev-file database. Keycloak 26.7.x may print a deprecation warning when the production profile still relies on that default:

WARNING: Usage of the default value for the db option in the production profile is deprecated. Please explicitly set the db instead.

Wire PostgreSQL in Configure Keycloak with PostgreSQL for durable storage. This article keeps the embedded database only to isolate the mode difference.

Why start fails when start-dev works

The fastest way to see the break is to run production start with no hostname or HTTP/TLS settings. Remove any leftover lab container so the name is free:

podman rm -f keycloak-mode-lab 2>/dev/null || true

Start Keycloak with production start and no extra environment variables. Host port 8081 avoids colliding with a start-dev lab on 8080:

podman run -d --name keycloak-mode-lab -p 127.0.0.1:8081:8080 quay.io/keycloak/keycloak:26.7.3 start

The container exits quickly. Read the logs:

podman logs keycloak-mode-lab

Changes detected in configuration. Updating the server image.
WARNING: Usage of the default value for the db option in the production profile is deprecated. Please explicitly set the db instead.
WARNING: With HTTPS not enabled, `proxy-headers` unset, and `hostname-strict=false`, the server is running in an insecure context. Secure contexts are required for full functionality, including cross-origin cookies. Also if you are using a proxy, requests from the proxy to the server will fail CORS checks with 403s because the wrong origin will be determined. Make sure `proxy-headers` are configured properly.
Key material not provided to setup HTTPS. Please configure your keys/certificates, or if HTTPS access is not needed see the `http-enabled` option. If you meant to start the server in development mode, see the `start-dev` command.

In this test, Keycloak stopped because HTTPS key material was missing. Production mode also expects hostname configuration, which is why the working command below explicitly sets KC_HOSTNAME=localhost.

Fix production start for a local HTTP lab

For a lab-only production-profile container on loopback, set hostname and enable HTTP. localhost is used only because this example is intentionally bound to loopback on the same machine. In a real deployment, set KC_HOSTNAME to the public hostname users access.

Remove the failed container first:

podman rm -f keycloak-mode-lab

Then run production start with explicit values:

podman run -d \
  --name keycloak-mode-lab \
  -p 127.0.0.1:8081:8080 \
  -e KC_HOSTNAME=localhost \
  -e KC_HTTP_ENABLED=true \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD='ChangeMe!2026' \
  quay.io/keycloak/keycloak:26.7.3 \
  start

Wait for the listening line in the logs:

podman logs keycloak-mode-lab

Changes detected in configuration. Updating the server image.
WARNING: Usage of the default value for the db option in the production profile is deprecated. Please explicitly set the db instead.
Next time you run the server, just add --optimized to the command to ensure this build is used.
2026-09-18 17:27:09,968 INFO  [io.quarkus] (main) Keycloak 26.7.3 on JVM (powered by Quarkus 3.33.3.1) started in 53.673s. Listening on: http://0.0.0.0:8080
2026-09-18 17:27:09,970 INFO  [io.quarkus] (main) Profile prod activated.

Profile prod activated confirms you are no longer in start-dev. Listening on: http://0.0.0.0:8080 is normal inside the container; -p 127.0.0.1:8081:8080 still limits access to localhost on the host.

Confirm HTTP responds:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8081/

302

HTTP 302 is expected. Keycloak redirects to its welcome route even in production profile when HTTP is enabled for the lab.

Can production Keycloak use HTTP?

Yes, when TLS terminates before Keycloak, not when browsers hit Keycloak directly on port 8080 without encryption.

• Direct TLS — Keycloak handles HTTPS itself with certificates and https-* settings
• Edge TLS termination — users connect to the proxy over HTTPS, while the proxy connects to Keycloak over HTTP

With edge TLS termination, enable Keycloak HTTP and configure proxy headers so Keycloak still generates HTTPS URLs for users. A typical pattern is start --hostname https://my.keycloak.org --http-enabled true (or the matching KC_* environment variables) plus proxy-headers. Skipping both HTTPS material and http-enabled is what triggers the Key material not provided error in the previous section.

For certificate paths and proxy header combinations, see Keycloak HTTPS and TLS and Keycloak reverse proxy.

Does start-dev require the dev database?

No. Development mode and database choice are separate settings.

You can run start-dev with PostgreSQL when you want development-mode defaults while testing against an external database. It is still development mode.

Likewise, start with PostgreSQL and KC_HTTP_ENABLED=true on localhost is still the production profile. Hostname rules, cache behavior, and HTTPS expectations follow start, not start-dev.

Cache differences

Keycloak uses Infinispan for realms, sessions, and related data. start-dev uses local cache and disables clustering. start uses the production distributed-cache setup.

For cluster topology and discovery options, see Configuring distributed caches.

Is start --optimized another Keycloak mode?

No. --optimized does not select development or production mode. start --optimized still runs production mode; it tells Keycloak to use a server that has already been built instead of performing the startup build/check.

For Dockerfile/Containerfile examples and kc.sh build, see Build an optimized Keycloak container.

Which mode should you use?

Use start-dev when you deliberately want development defaults. Use start whenever you need to test or deploy production-mode behavior.

Common start vs start-dev problems

Summary

start-dev runs Keycloak with development defaults: HTTP enabled, relaxed hostname handling, local caching, and reduced theme caching. start runs the production profile, where hostname and secure transport must be configured explicitly.

Database choice is separate from the startup mode, and --optimized is a startup optimization rather than another mode. For production deployments, use start with the appropriate hostname, TLS/proxy, database, and cache configuration.

References

• Configuring Keycloak — development and production defaults, including that start and start-dev can invoke build
• Configuring the hostname (v2) — production hostname rules and edge TLS termination with HTTP enabled
• Configuring distributed caches — production cache and discovery defaults
• Running Keycloak in a container — official image commands including start and start-dev