Docker / Podman Deployment

This project includes a multi-stage Dockerfile for containerized deployment. All commands work with both Docker and Podman — substitute as needed.

Multi-Stage Build Overview

Stage	Base Image	Purpose
Builder	maven:3.9-eclipse-temurin-21	Compiles source and produces the provider JAR
Runtime	quay.io/keycloak/keycloak:26.7.3	Copies the JAR and runs kc.sh build

Both stages use the KEYCLOAK_VERSION build argument (default 26.7.3). To try another Keycloak version, pass it at build time, for example docker build --build-arg KEYCLOAK_VERSION=26.6.2 -t keycloak-2fa-email:latest .

Build the Image

Docker

docker build -t keycloak-2fa-email:latest .

Podman

podman build --tls-verify=false -t keycloak-2fa-email:latest .

note

--tls-verify=false may be needed if Podman encounters certificate verification issues.

Run the Container

Docker

docker run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  keycloak-2fa-email:latest \
  start-dev

Podman

podman run -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  keycloak-2fa-email:latest \
  start-dev

Keycloak is available at http://localhost:8080 once started.

Using Docker Compose

The project includes a docker-compose.yml:

Docker

docker-compose up

Podman

podman-compose up

Production Deployment

warning

start-dev must not be used in production. Use start with a real database and TLS certificates.

Docker

docker run -d \
  --name keycloak-prod \
  -p 8443:8443 \
  -e KC_HOSTNAME=keycloak.example.com \
  -e KC_HTTPS_CERTIFICATE_FILE=/path/to/cert.pem \
  -e KC_HTTPS_CERTIFICATE_KEY_FILE=/path/to/key.pem \
  -e KC_DB=postgres \
  -e KC_DB_URL=jdbc:postgresql://db/keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  keycloak-2fa-email:latest \
  start

Podman

podman run -d \
  --name keycloak-prod \
  -p 8443:8443 \
  -e KC_HOSTNAME=keycloak.example.com \
  -e KC_HTTPS_CERTIFICATE_FILE=/path/to/cert.pem \
  -e KC_HTTPS_CERTIFICATE_KEY_FILE=/path/to/key.pem \
  -e KC_DB=postgres \
  -e KC_DB_URL=jdbc:postgresql://db/keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  keycloak-2fa-email:latest \
  start

Container Management

# Stop
docker stop keycloak-test

# Start
docker start keycloak-test

# Remove
docker stop keycloak-test && docker rm keycloak-test

# Remove image
docker rmi keycloak-2fa-email:latest

Rebuild After Code Changes

docker build -t keycloak-2fa-email:latest .
docker stop keycloak-test && docker rm keycloak-test
docker run -d --name keycloak-test \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  keycloak-2fa-email:latest start-dev

What's Next?

• Local Testing Guide — full step-by-step test walkthrough
• Authentication Flow Setup