Skip to content

Deploying Keycloak on Google App Engine


Do you want to know the process of how we deploy and run Keycloak on Google’s App Engine? Are you furthermore interested to know what are the pitfalls that we face and how we encounter those? Then keep reading! 

Google’s documentation describes App Engine as “a fully managed, serverless platform for developing and hosting web applications at scale”. It lets you run codes and applications without worrying about provisioning and scaling your app instances. App Engine works with languages such as Java, Go and Python, but it also allows you to run containers by passing just a Dockerfile.

The Challenge

Keycloak is an open source Identity and Access Management solution that is aimed at modern applications and services. Our client runs all applications and services on Google Cloud Platform, therefore they wanted Keycloak to land there as well.

Two important factors that had to be taken into account are: ease of maintenance and low cost. Easy maintenance means; we want Keycloak to run inside a container. This left us with two viable options on which Google Cloud service to use:

  1. Run on Google Kubernetes Engine (GKE)
  2. Run on Google App Engine (GAE)

There were no other services making use of GKE, so Keycloak would be the first. This means that an entire GKE cluster would be operating only for Keycloak, which is quite costly. Also, the amount of overhead and maintenance in order to do this directed us to start using GAE.


We want to add a custom login theme to Keycloak which requires fiddling with files and adding them into the container. This can be done by App Engine as well, but deploying a container can take up to 10 minutes. To be able to iterate fast, we build a base image locally and push it to Google Container Registry (GCR). Then, in the Dockerfile we pass to GAE only specific deployment configuration (e.g. database connection details).

Drawn in a diagram, the process looks like this:


In order to run containers on GAE, Google needs service configuration app.yaml and a Dockerfile.

# app.yaml

runtime: custom

env: flex

service: my-keycloak-service


     instances: 1


  cpu: 2

  memory_gb: 8

  disk_size_gb: 10


  path: "/"

  check_interval_sec: 30

  timeout_sec: 10

  failure_threshold: 5

  success_threshold: 2

  initial_delay_sec: 300


  path: "/"

  timeout_sec: 10

  check_interval_sec: 30

  failure_threshold: 5

  success_threshold: 2

  app_start_timeout_sec: 180

In app.yaml you define the runtime of the service, its environment and a service name. The other options are optional. In the case of running containers, runtime has to be set to custom and env to flex.

Note: Although its optional to specify liveness_check and readiness_check, you should do this. Google will execute health checks every 30 seconds and will restart the service if the checks fail too often. For more information, see the documentation.

# Dockerfile




ENV DB_DATABASE myKeycloak_db

ENV DB_USER db_user





ENV JAVA_OPTS -server -Xms2048m -Xmx6144m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m -Djboss.modules.system.pkgs=org.jboss.byteman 

The database that Keycloak connects to is a Mysql instance with only a private IP. In order to connect through the private IP, the database must be running in the same region as GAE.

In order to deploy the service to GAE, first specify your project:

gcloud init

Then run:

gcloud app deploy


To conclude, using Google App Engine provides the ability to quickly run containerized solutions without worrying about the underlying infrastructure. Deploying can however take a long time. To deal with this, development and testing of the image is done locally and pushed to Google Container Registry. From there, only environment variables in the image are changed depending on the destination environment.

This way, new features and changes in Keycloak can be delivered quickly and in a sustainable way.

Join our open & innovative culture

Open, accessible and ambitious are the keywords of our organizational culture. We encourage making mistakes, we strive to do better every day and love to have fun. Doing work you love with brilliant people is what it’s all about.