Skip to content

Hostname Configuration

Hostname Configuration with set_hostname Script

The set_hostname script is a utility provided with the application to help configure the necessary hostname parameters and automatically generate HTTPS certificates. This script ensures that the correct browser URL is set up for the application, including:

  1. Frontend Configuration: Ensures the browser can access the application.
  2. Backend Configuration: Allows proper routing of requests to the backend services.
  3. CORS (Cross-Origin Resource Sharing): Configures the application to handle requests from different origins securely.
  4. TLS Certificate Generation: Automatically creates and signs SSL certificates for secure communication.

Setting the hostname correctly is essential for users to access the application through their web browsers and for the application to handle requests and responses securely.

Purpose of the set_hostname Script

The set_hostname script specifically configures the browser URL for the application and handles certificate generation. This includes:

  1. Setting the domain name or IP address.
  2. Generating self-signed certificates automatically if no custom certificate is provided.
  3. Signing certificates with the pre-generated root CA for internal trust.

HTTPS is now mandatory

Starting with the latest Keycloak version, HTTPS is required for all deployments. The set_hostname script automatically generates self-signed certificates if you don't provide your own.

How to Use the set_hostname Script

Required Variable

When running the script, you will need the following variable:

1. Hostname: This can be an IP address (e.g., 192.168.1.100) or a DNS name (e.g., example.com).

Use the following commands based on your operating system to execute the set_hostname script:

Bash
./config.sh set_hostname

2. Provide the Hostname: When prompted, enter the hostname with HTTPS protocol (IP or DNS) for the application.

3. Verify Configuration: After running the script, ensure that the hostname is correctly configured in the application's settings.

4. Confirm Updates: Type y when prompted to proceed with updating the docker-compose.yml file.

Certificate Generation

The script will automatically:

  • Generate a private key for the router
  • Create a Certificate Signing Request (CSR)
  • Sign the certificate with the root CA
  • Configure the certificate with appropriate Subject Alternative Names (SANs) for both the hostname and localhost

Verify Configuration

After running the script, you will see:

  • Confirmation that docker-compose.yml has been updated
  • Location of the generated certificate files (./tls/router.key and ./tls/router.crt)
  • The frontend URL where you can access the application