Skip to main content

Migrate a Keycloak Embedded Database to an External Database Service (Linux)

Note

It is necessary to migrate the embedded database Keycloak comes with which is only intended for development use-cases and is not suitable for production use-cases as stated in the Keycloak online documentation.

For productive deployments of Keycloak we use the PostgreSQL database (currently supported and tested version of PostgreSQL is version 16). Before migrating the Keycloak DB make a backup of your "poolparty_home"/auth_service directory.

Below we describe how you can install and configure a PostgreSQL DB which is the tested and supported database to be used with Keycloak and PoolParty.

Install the database as specified under Linux distribution. Connect to the server using sudo -i -u postgres and run the following commands:

CREATE DATABASE keycloakdb;
CREATE USER keycloakdbuser WITH ENCRYPTED PASSWORD 'keycloakdbpass';
GRANT ALL PRIVILEGES ON DATABASE keycloakdb TO keycloakdbuser;

Open a new terminal window and stop all PoolParty services. Make a dump of the Keycloak database. To create the dump (backup) of the Keycloak DB proceed as follows:

  1. Change directory to: "poolparty_home"/auth_service/keycloak/bin.

  2. Run ./kc.sh export --file keycloak.json.

  3. Edit "poolparty_home"/auth_service/keycloak/conf.

  4. Make sure that the lines 9 through 15 in the keycloak.conf look like this:

    # The database vendor.
db=postgres

# The username of the database user.
db-username=keycloakdbuser

# The password of the database user.
db-password=keycloakdbpass

# The full database JDBC URL. If not provided, a default URL is set based on the selected database vendor.
db-url=jdbc:postgresql://localhost:5432/keycloakdb

****************************************************************************************

  5. Run ./kc.sh build.

  6. To enable configuration changes run ./kc.sh import --file keycloak.json.

  7. Then restart the PoolParty services.

If you have docker or podman installed you can use the docker-compose files to run the database in a container.

An example of docker compose:

version: '3.9'
services:
 postgres:
  image: postgres:16-alpine
  ports:
   - 5432:5432
  volumes:
   - /home/test-user/kc_postgresdb/db/postgres:/var/lib/postgresql/data
  environment:
   - POSTGRES_PASSWORD=keycloak
   - POSTGRES_USER=keycloak
   - POSTGRES_DB=keycloak

An example of podman:

services:
  pgdb:
    image: postgres:16
    container_name: postgres
    environment:
      - VERSION=podman
      - POSTGRES_PASSWORD=keycloak
      - POSTGRES_USER=keycloak
      - POSTGRES_DB=keycloak
      - PGDATA=/var/lib/postgresql/data
    restart: always
    ports: 5432:5432
    volumes:
      - /yourpath/pg_db:/var/lib/postgresql/data:z

Now run docker compose respectively podman compose in detached mode.

Afterwards proceed with the migration of keycloak data.

To migrate a PoolParty realm-specific Keycloak embedded database to an external database service for Linux, do the following:

  1. Stop the PoolParty service if it's running at /path/to/poolparty/bin/poolparty.

  2. Do a complete backup of data at /path/to/poolparty.

  3. Go to the /path/to/poolparty/bin folder.

  4. Put the script into this folder. The script is called migrate-keycloak-to-db in this example and you can find it below.

  5. Make the migrate-keycloak-to-db file executable with chmod +x /path/to/poolparty/bin/migrate-keycloak-to-db.

  6. Edit the migrate-keycloak-to-db file and define the following:

    1. DB_VENDOR

    2. DB_USERNAME

    3. DB_PASSWORD

    4. DB_HOST

    5. DB_PORT

    6. DB_NAME

    Here is an example screenshot:

    image2022-11-11_10-14-25.png

  7. Execute ./migrate-keycloak-to-db to migrate to the defined database service.

    Tip

    If something goes wrong (for example you have provided a wrong database password), you can either recover the installation from the backup created in step 2 or execute ./migrate-keycloak-to-db rollback.

    Caution

    It is important to run the rollback before re-running migration with changed settings.

In this section: