To change the host for a Keycloak Docker container, you must modify the
KC_HOSTNAME environment variable in your docker-compose file or run command. This setting defines the public hostname used to generate absolute URLs for redirects and links. You should also configure
KC_PROXY_HEADERS if running behind a reverse proxy like Nginx or Apache to ensure correct protocol handling.
Understanding Hostname Configuration
Keycloak generates URLs dynamically based on the request it receives. By default, it uses the hostname from the incoming HTTP request headers. However, in containerized environments, this often results in incorrect URLs pointing to internal container IDs or localhost instead of the actual public domain. The
KC_HOSTNAME environment variable allows you to explicitly set the base URL that Keycloak will use for all generated links, including login redirects and API endpoints.
When deploying Keycloak via Docker, it is crucial to distinguish between the internal service name used by Docker networking and the external hostname exposed to users. If you are accessing Keycloak through a subdomain like
auth.example.com, but the container reports its own internal network address, authentication flows will break because the browser will be redirected to an unreachable internal IP. Setting the correct hostname ensures that the Identity Provider (IDP) communicates valid URIs back to client applications.
For more details on how files are shared between your docker container and host during configuration updates, you might find our guide on
shared files between docker container and host helpful for managing persistent storage needs.
Modifying Docker Compose Configuration
The most common way to deploy Keycloak is using a
docker-compose.yml file. To change the host, you need to add specific environment variables under the keycloak service definition. Below is a standard example of how to structure this configuration.
version: '3.8'
services:
keycloak:
image: quay.io/keycloak/keycloak:latest
environment:
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: password
KC_HOSTNAME: auth.example.com
KC_HTTP_ENABLED: true
KC_PROXY_HEADERS: xforwarded
ports:
- "8080:8080"
depends_on:
- postgres
In this configuration,
KC_HOSTNAME is set to
auth.example.com. This tells Keycloak that all outgoing requests and generated links should assume this domain. Additionally,
KC_PROXY_HEADERS: xforwarded is critical when Keycloak sits behind a reverse proxy. It instructs Keycloak to trust the
X-Forwarded-Host and
X-Forwarded-Proto headers sent by the proxy, ensuring that HTTPS is correctly recognized even if the connection between the proxy and the container is HTTP.
If you are facing issues with pulling images or configuring containers in more complex setups, such as Kubernetes, reviewing troubleshooting steps for
troubleshooting docker container pulling issue in kubernetes may provide additional context on environment stability.
Reverse Proxy Considerations
Changing the Keycloak hostname is rarely done in isolation. It is almost always paired with a reverse proxy configuration. Whether you use Nginx, Apache, or Traefik, the proxy must forward the correct host header to the Keycloak container. If the proxy strips or modifies the host header incorrectly, Keycloak may ignore the
KC_HOSTNAME setting or generate malformed URLs.
Ensure your reverse proxy configuration includes directives to pass the original host. For Nginx, this typically involves setting
proxy_set_header Host $host; and
proxy_set_header X-Forwarded-Proto $scheme;. Without these headers, Keycloak cannot determine the correct scheme (HTTP vs HTTPS) or the intended domain, leading to mixed content warnings or redirect loops in the browser.
It is also important to consider security implications. Exposing Keycloak directly without a reverse proxy can lead to certificate management complexities. Using a reverse proxy allows you to terminate SSL/TLS at the edge, keeping the internal communication simpler while maintaining security standards for end-users.
Verification and Testing
After updating your environment variables and restarting the container, verify the configuration by checking the admin console. Navigate to the realm settings and look at the "Login" tab. Ensure that the "Standard Flow Redirect URI" and other callback URLs reflect your new hostname. You can also use browser developer tools to inspect network requests during a login attempt. Look for the
Location header in redirect responses; it should point to your specified
KC_HOSTNAME, not the internal container IP.
If you encounter mounting issues or configuration conflicts after changing hosts, especially in development environments like DDEV, you might want to check resources on
fixing Mutagen/Docker Config Issues with DDEV and Mounting Code to /srv Directory to understand potential filesystem synchronization delays.
Frequently Asked Questions
What happens if I don't set KC_HOSTNAME?
Keycloak will derive the hostname from the incoming request's Host header. In Docker environments, this often leads to internal container names or IPs being used in URLs, causing authentication failures for clients that cannot resolve those internal addresses.
Do I need to restart the container after changing the hostname?
Yes, environment variables are read during the startup process. Any changes to
KC_HOSTNAME require a full restart of the Keycloak container to take effect. A simple reload or cache clear is insufficient.
Can I use KC_HOSTNAME with HTTPS?
Yes, but you must also ensure that
KC_HTTPS_CERTIFICATE_FILE and
KC_HTTPS_CERTIFICATE_KEY_FILE are configured if you are not terminating SSL at a reverse proxy. Alternatively, set
KC_PROXY_HEADERS to trust the proxy's TLS termination.
Why are my redirects still broken after setting the hostname?
Check if your reverse proxy is correctly forwarding the
X-Forwarded-Host and
X-Forwarded-Proto headers. If these are missing, Keycloak may not recognize the secure context or the correct domain despite the
KC_HOSTNAME setting.
Does KC_HOSTNAME affect database connections?
No,
KC_HOSTNAME only affects the public-facing URLs generated by Keycloak. Database connections are controlled by
KC_DB_URL and related database-specific environment variables, which remain independent of the public hostname.