Guide for Setting Up Keycloak in Docker with SSL TLS Certificates from Let's Encrypt - JU-DEV-Bootcamps/ERAS GitHub Wiki

This article presents a detailed and tested guide for deploying a Keycloak server using Docker and SSL/TLS certificates generated by Let's Encrypt. The instructions are based on reliable sources and have been validated to ensure a successful process.

The guide was originally written in 2021 and updated in 2023. It is designed to streamline the configuration process and facilitate the creation of environments for demos, proofs of concept, or tests in production.

Before you begin, make sure you meet the following prerequisites:

• Operating System: Ubuntu 20.04 or later.
• DNS: Ensure you have a Fully Qualified Domain Name (FQDN) that is resolvable.
• Firewall Rules: Ensure the following ports are open:
  • 22 (SSH)
  • 443 (SSL/TLS)
  • 80 (HTTP)
• SSL/TLS Certificates with Let's Encrypt: To generate the certificates.

1. SSH to the Keycloak server: Connect to the Keycloak server.

2. Install Certbot: Run the following commands to install Certbot, the official Let's Encrypt tool.

   sudo snap install --classic certbot
   sudo ln -s /snap/bin/certbot /usr/bin/certbot

3. Generate the Certificate: Run the following command to generate the SSL/TLS certificates.

   sudo certbot certonly --standalone

   When finished, you will have the fullchain.pem (certificate) and privkey.pem (private key) files.

1. Configure the Docker repository: Update the package index and install the required packages to use repositories over HTTPS..

   sudo apt-get update
   sudo apt-get install ca-certificates curl gnupg

2. Add Docker's official GPG key: Install and configure the GPG key for Docker's repository.

   sudo install -m 0755 -d /etc/apt/keyrings
   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
   sudo chmod a+r /etc/apt/keyrings/docker.gpg

3. Add Docker's repository: Configure the stable Docker repository.

   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4. Install Docker and Docker Compose: Install Docker and Docker Compose.

   sudo apt-get update
   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

5. Start and configure Docker: Start Docker and configure it as a service.

   sudo systemctl start docker
   sudo useradd <username>
   sudo usermod -aG docker <username>
   sudo systemctl enable docker.service
   sudo systemctl enable containerd.service

6. Verify Docker installation:

   sudo docker version
   sudo docker compose version

1. Move the certificates: Copy the fullchain.pem and privkey.pem files to a location accessible by Docker, for example:

   mkdir -p /home/user/keycloak/certs
   cp /etc/letsencrypt/live/<your-domain>/fullchain.pem /home/user/keycloak/certs/
   cp /etc/letsencrypt/live/<your-domain>/privkey.pem /home/user/keycloak/certs/

2. Set permissions: Ensure Docker can access the certificate files.

   sudo chmod 655 /home/user/keycloak/certs/*

3. File Structure: The file structure should look like this:

   ├── keycloak.yml
   ├── certs
   │   ├── fullchain.pem  
   │   └── privkey.pem

Here is an example docker-compose.yml configuration:

version: '3'
services:
 keycloak:
   image: quay.io/keycloak/keycloak:latest
   container_name: keycloak
   restart: always
   ports:
     - 80:8080
     - 443:8443
   volumes:
     - ./certs/fullchain.pem:/etc/x509/https/tls.crt
     - ./certs/privkey.pem:/etc/x509/https/tls.key
   environment:
     - KEYCLOAK_ADMIN=admin
     - KEYCLOAK_ADMIN_PASSWORD=password
     - KC_HOSTNAME=<your-domain>
     - KC_HTTPS_CERTIFICATE_FILE=/etc/x509/https/tls.crt
     - KC_HTTPS_CERTIFICATE_KEY_FILE=/etc/x509/https/tls.key
   command:
     - start-dev

1. Bring up the Keycloak container: Run the following command to start the Keycloak service using Docker Compose.

   sudo docker-compose -f keycloak.yml up

2. Verify the deployment:: Open a browser and navigate to https://. If everything is set up correctly, you should see the Keycloak admin interface.