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 sudi -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:
Change directory to:
"poolparty_home"/auth_service/keycloak/bin
.Run
./kc.sh export --file keycloak.json
.Edit
"poolparty_home"/auth_service/keycloak/conf
.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 ****************************************************************************************
Run
./kc.sh build
.To enable configuration changes run
./kc.sh import --file keycloak.json
.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:
Stop the PoolParty service if it's running at
/path/to/poolparty/bin/poolparty
.Do a complete backup of data at
/path/to/poolparty
.Go to the
/path/to/poolparty/bin
folder.Put the script into this folder. The script is called
migrate-keycloak-to-db
in this example and you can find it below.Make the
migrate-keycloak-to-db
file executable with chmod +x /path/to/poolparty/bin/migrate-keycloak-to-db.Edit the
migrate-keycloak-to-db
file and define the following:DB_VENDOR
DB_USERNAME
DB_PASSWORD
DB_HOST
DB_PORT
DB_NAME
Here is an example screenshot:
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.