# How to Deploy Keycloak With xCloud One Click Apps

> Deploy Keycloak single sign-on on xCloud from the One-Click Apps catalog: server size, the bootstrap admin, first sign-in, a safe first setup, backups and updates.

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](/_landing/docs/deploy-keycloak-with-xcloud-image-1.png)

## 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](/_landing/docs/deploy-keycloak-with-xcloud-image-2.png)

**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](/_landing/docs/deploy-keycloak-with-xcloud-image-3.png)

**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](/_landing/docs/deploy-keycloak-with-xcloud-image-4.png)

**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](/_landing/docs/deploy-keycloak-with-xcloud-image-5.png)

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](/docs/backup-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](/docs/update-a-one-click-app-and-edit-its-docker-compose-in-xcloud/). 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.

## Related resources

- [Keycloak hosting on xCloud](/keycloak-hosting/): plans and what is included
- [How to use One-Click App Templates](/docs/how-to-use-one-click-app-templates-in-xcloud/): App Actions, the environment editor and events
- [Update a One Click App and edit its Docker Compose](/docs/update-a-one-click-app-and-edit-its-docker-compose-in-xcloud/)
- [Back up and restore Docker apps](/docs/backup-and-restore-docker-apps/)
- [Browse the One-Click Apps catalog](/one-click-apps/)
- Keycloak's own guides: [Server Administration](https://www.keycloak.org/docs/latest/server_admin/) and [Upgrading](https://www.keycloak.org/docs/latest/upgrading/)

If you run into any issues while deploying Keycloak, feel free to reach out to our [support team](/docs/access-built-in-support-portal-in-xcloud/).
