This repository deploys the Keycloak Identity and Access Manangement Solution
to Dokku. It is based on Keycloak's official docker image with some slight modifications to use the
Heroku variable for PORT and DATABASE_URL properly.
The instructions and examples below are targeted at an audience looking to use Keycloak on a production(ish) installation of Dokku requiring HTTPS with a properly signed certificate from Let's Encrypt.
Dokku Installation Prerequisites
- A host with at least 2GB of RAM. (Keycloak is a Java beast!)
- Dokku 0.24.7 or greater installed.
- Dokku hostname configured to match the associated domain name.
- The fake "example.com" will be used in examples below.
- Dokku configured to utilize virtual hosts (vhosts) for apps.
- A sense of joy!
All of the commands in this section need to be executed on the Dokku host machine!
PostgreSQL
dokku plugin:install https://github.com/dokku/dokku-postgres.git
Let's Encrypt
dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
You can name the Keycloak app and database anything you like, but for this example we'll stick with "keycloak" to keep things simple.
All of the commands in this section need to be executed on the Dokku host machine!
Create App
dokku apps:create keycloak
Create PostgreSQL Database
dokku postgres:create keycloakdb
Link Database to App
dokku postgres:link keycloakdb keycloak
Set Keycloak Admin Credentials
Provide a strong password for the Keycloak admin account.
dokku config:set --no-restart keycloak KEYCLOAK_USER=admin KEYCLOAK_PASSWORD=strongpassword
Enable Keycloak Proxy Forwarding
Enable proxy forwarding in order for Keycloak to work correctly behind the Nginx reverse proxy.
dokku config:set --no-restart keycloak PROXY_ADDRESS_FORWARDING=true
Configure Keycloak Hostname
The hostname must match the name of the Dokku vhost app and domain name!
dokku config:set --no-restart keycloak KEYCLOAK_HOSTNAME=keycloak.example.com
dokku domains:set keycloak keycloak.example.com
Configure Keycloak Port and Proxy Map
dokku config:set --no-restart keycloak KEYCLOAK_HTTP_PORT=80
dokku ports:add keycloak http:80:80
Before fully enabling HTTPS with a signed certificate from Let's Encrypt, the Dokku app must be deployed and tested.
All of the commands in this section need to be executed on your local machine!
Clone "keycloak-dokku" Repo
git clone https://github.com/davidpodhola/keycloak-dokku.git && cd keycloak-dokku
Add Git Remote to Dokku App
You can name the remote anything like, but we'll be using "dokku" to keep things simple.
git remote add dokku [email protected]:keycloak
Deploy "keycloak-dokku"
Deployment can take a while the first time.
git push dokku master
Verify Deployment
Keycloak is a JBoss Java app which means it has a long startup time. You may need to wait as long as 5 minutes for the service to be ready. Execute the following command on the on the Dokku host machine to check progress.
dokku logs -t keycloak
Once the Keycloak deployment has been completed, verify that the service is accessible by navigating to
http://keycloak.example.com/auth/admin in your browser. DO NOT LOGIN! THIS IS AN UNSAFE HTTP
CONNECTION! Just verify that the login screen is accessible.
All of the commands in this section need to be executed on the Dokku host machine!
dokku config:set --no-restart keycloak [email protected]
dokku letsencrypt:enable keycloak
Navigate to https://keycloak.example.com/auth/admin and login with your admin credentials!