- Keycloak v26+ running
- Basic Keycloak admin knowledge
- Familiarity with FreeMarker templates (FTL)
- Maven 3.6.3+
- Java 21+
- Rails 8 project for integration testing
- Visual Studio Code
Customize Keycloak login, account, and email screens to match your Rails app branding.
docker rm -f $(docker ps -a -q) && docker system prune -adocker network create demo-networkdocker run -d --name keycloak --network demo-network -p 8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
quay.io/keycloak/keycloak:latest start-devdocker run -d -p 8025:8025 --name demo-mail --network demo-network mailhog/mailhogEDITOR="code --wait" rails credentials:editkeycloak:
client_id: your-client-id
client_secret: your-client-secret
host: http://localhost
port: 8080
realm: quickstart
redirect_uri: http://localhost:3000/auth/keycloak/callback
secret_key_base: <generated>
mvn archetype:generate \
-DgroupId=com.bootlabs \
-DartifactId=keycloak-custom-theme \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=false
rm -rf src/
mkdir -p src/main/resources/theme/keycloak-custom-theme/loginlogin/login.ftl → Login page template
login/resources/css/login.css → Styles
login/resources/img/logo.png → Logo
theme.properties → Theme metadata
scripts/update-footer.sh → Footer script with Git commit/version
#!/bin/bash
set -e
GIT_HASH=$(git rev-parse --short HEAD)
DATE=$(date +"%Y-%m-%d")
YEAR=$(date +"%Y")
FOOTER_FILE="src/main/resources/theme/keycloak-custom-theme/login/footer.ftl"
cat <<EOF > "$FOOTER_FILE"
<#macro content>
<footer id="kc-footer" style="display:flex;flex-direction:column;align-items:center;text-align:center;padding:1rem;font-size:0.85rem;color:#666;">
<p>© $YEAR Company inc — All right reserved.</p>
<p>Version $GIT_HASH ($DATE)</p>
<p>Support: <a href="mailto:[email protected]">[email protected]</a></p>
</footer>
</#macro>
EOF
echo "✅ Footer updated successfully in $FOOTER_FILE"mvn clean installThis runs update-footer.sh and packages the theme as a JAR
Theme is deployed to Keycloak Docker container via Maven exec plugin
Go to Keycloak > Realm quickstart > Client test-cli > Realm settings > Themes
Set Login Theme to keycloak-custom-theme and save
Run Rails app:
bin/devVisit localhost:3000 and click Login with Keycloak