How to Deploy Keycloak With xCloud One Click Apps

Updated November 18, 2026 · 9 min read

Summarize with:
Share:

Deploy Keycloak from Sites → New Site → One-Click Apps → Keycloak → choose a server → Continue → Demo Site or Go Live → Next. xCloud supplies the Keycloak template with its PostgreSQL database, so you do not write a docker-compose.yml. This guide is for xCloud users who want their own single sign-on server for apps and teams, with OpenID Connect, OAuth 2.0 and SAML.

The One-Click Apps catalog searched for Keycloak, with the Keycloak card highlighted

What the Keycloak template includes

Part What it does Good to know
Keycloak The sign-in server and the Admin Console Runs in production mode. It is only reachable through your domain over HTTPS, not by server IP and port.
PostgreSQL 17 Stores realms, users, clients, keys and settings Lives on its own data volume, keycloak_db. This is the data you back up.
Bootstrap admin A temporary admin for your first sign-in You choose the username. xCloud generates the password and shows it on the site.
Database login The database name, user and password xCloud generates them. You never type them in.

Before you start

Requirement Recommendation Why it matters
Server An NGINX server. xCloud installs Docker on it if it is not there yet. Keycloak runs in Docker. OpenLiteSpeed servers can’t run Docker.
Memory At least 4 GB RAM Keycloak runs on Java and sizes its memory from the server. 4 GB leaves room for PostgreSQL too.
CPU and disk At least 2 vCPU and 5 GB free disk The minimum the Keycloak template asks for. Add more for many users or frequent logins.
Domain DNS access if you choose Go Live Keycloak builds its sign-in and redirect links from your domain.

Step 1: Find Keycloak in the catalog

Go to Sites → New Site. Type Keycloak in Search apps… and click the Keycloak card.

Expected result: The Keycloak page shows Runs on Nginx, Docker, the recommended size (4 GB RAM · 2 vCPU · 5 GB disk) and the version it installs.

Step 2: Choose where it runs

Under Where should it run?, click one of your servers, or Deploy on a new server to create a dedicated one. Then click Continue.

Choosing an existing NGINX server under ‘Where should it run?’ on the Keycloak app page

Expected result: xCloud opens the Install Keycloak Into form for the server you chose. A server that is too small or on the wrong stack can’t be picked, and its card says why.

Step 3: Fill in the site form

  1. Enter a Site Title, for example Keycloak SSO. Tags are optional.
  2. Under Domain Setup, choose Demo Site to try Keycloak on a test domain, or Go Live to use your own domain.
  3. Keep admin in Bootstrap Admin Username, or type another name. It may use letters, numbers, dashes and underscores.

The Bootstrap Admin Username field on the Install Keycloak form, under Site Title and Domain Setup

Expected result: The form shows your title, the domain and the admin username.

Step 4: Click Next and wait for the setup

Click Next. xCloud shows the setup progress: it checks the server, installs Docker if needed, sets up the app, then adds SSL and NGINX.

Expected result: The site opens on its overview when the setup is done. Keycloak’s first start also prepares its database, so the sign-in page can take a few more minutes to load.

Step 5: Copy the admin sign-in details

On the site’s Site Overview, the Keycloak Credentials card lists the Keycloak URL, the Admin Console link, the Bootstrap Admin Username and the Bootstrap Admin Password. The card also shows the installed Keycloak version. Click Copy next to the password and save it in your password manager.

The Keycloak Credentials card on Site Overview with Keycloak URL, Admin Console, Bootstrap Admin Username and Bootstrap Admin Password

Expected result: You have the Admin Console link (your domain followed by /admin/) and the temporary admin login.

Step 6: Sign in and replace the temporary admin

Open the Admin Console link. Keycloak shows Sign in to your account. Enter the bootstrap admin username and password, then click Sign In.

The Keycloak ‘Sign in to your account’ page that opens from the Admin Console link

Then make Keycloak safe to use:

Setup task What to do How you know it worked
Permanent admin In the master realm, create a named admin user and give it only the admin roles it needs You can sign in as that user
Temporary admin Sign in as the permanent admin, then disable or delete the bootstrap admin The bootstrap login no longer works
Realm for your apps Create a new realm for your users and apps. Keep master for admins only Your apps’ users and clients live in the new realm
Email Add SMTP settings in the realm before you turn on password reset or email checks Keycloak sends a test email
Clients For each app, enter its exact redirect URIs and web origins. Avoid broad wildcards like * The app signs in and comes back to the right page

If the Admin Console does not load yet, wait a few minutes and refresh. The first start builds the server and sets up the database.

Back up and update Keycloak

Everything Keycloak knows (realms, users, clients, keys) is in its PostgreSQL database on the keycloak_db volume. Back it up before every change:

  • Take a database backup, for example with pg_dump, and keep a copy off the server. Back up and restore Docker apps covers the xCloud side.
  • Test a restore on a separate site before you rely on it.

The template pins one Keycloak version. App Actions → Update pulls that same version again, it does not upgrade you. To move to a newer Keycloak, read Keycloak’s upgrade notes, back up the database, then change the image tag as shown in Update a One Click App and edit its Docker Compose. Don’t change the PostgreSQL major version (17) without a database migration plan.

Changing KC_BOOTSTRAP_ADMIN_USERNAME or KC_BOOTSTRAP_ADMIN_PASSWORD in the environment later does nothing to existing admins. To change the database password, change it in PostgreSQL first, then update both POSTGRES_PASSWORD and KC_DB_PASSWORD in the environment editor and redeploy.

Troubleshooting

Problem Likely cause Fix
Your server can’t be selected It has less than 4 GB RAM, 2 vCPU or 5 GB free disk, or it runs OpenLiteSpeed Pick an NGINX server with enough room, or choose Deploy on a new server
The Keycloak URL shows an error right after setup Keycloak is still starting and preparing its database Wait a few minutes and refresh
The bootstrap password doesn’t work The temporary admin was already removed, or the password was copied with extra spaces Sign in with your permanent admin. Copy the password again from the Keycloak Credentials card
An app gets “Invalid redirect URI” The client’s redirect URI does not match the app’s exact URL Add the exact URL under the client’s valid redirect URIs
Keycloak is slow or restarts under load Not enough memory for Java and PostgreSQL Move to a larger server and watch memory in server monitoring

Frequently asked questions

Do I need a custom docker-compose.yml to deploy Keycloak on xCloud?

No. The One-Click Apps catalog supplies the Keycloak template. You pick Keycloak, choose a server, fill in the site form and click Next.

What size server does Keycloak need on xCloud?

The Keycloak template asks for at least 4 GB RAM, 2 vCPU and 5 GB of disk. Keycloak runs on Java and sizes its memory from what the server has, so give busy login traffic more room.

Can I change the admin password by editing the environment variables?

No. The bootstrap admin username and password only create the temporary admin the first time Keycloak starts. After that, manage admins inside the Keycloak Admin Console.

Does Update move my Keycloak to a newer version?

No. The template pins one Keycloak version, so Update pulls that same version again. To move to a newer Keycloak, back up the database first, then change the image tag on the app’s Compose page.

If you run into any issues while deploying Keycloak, feel free to reach out to our support team.