Skip to main content

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

We recommend migrating the embedded database Keycloak comes with to an external database service for Linux. For more information on the supported databases, refer to the Keycloak online documentation. Please make a backup of your "poolparty_home"/auth_service directory.

To migrate Keycloak embedded database you will have to install an external database. In our example we will install and configure a PostgreSQL. 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: