What is the best approach to migrate realm from v10 to v19 on a new server?

1

Keycloak newbie here.

Inherited an legacy keycloak (v10). I need to move some of the realm which some of the applications are current using, into a new server.

My initial plan is to do a clean v19 install, and do an realm export from v10, and import to v19. However, after doing some research, I think it’s not compatible. Please correct me if I’m wrong.

Has anyone has done similar upgrade before? What would be the best approach here?

Thanks a lot in advance.

2

Keycloak is designed with a migration mechanism that should work to upgrade between versions. People have reported various degrees of success with “big” upgrades. I would recommend the following steps:

  1. back up your database and import the backup to a test database instance
  2. try running v19 against that database, and see if the automatic db migration works
  3. if it doesn’t work, go incrementally by major version, one at a time (this is pretty easy if you just have a docker-compose file where you update the docker image every time you start)
  4. assuming you can get some combinations of upgrades to work, run the same series in production
3

Thank you @xgp for this info. Much appreciated!

Here’s my plan:

  1. setup a new db and import the export from current v10 keycloak.
  2. setup fresh v19 to connect to the db setup in 1)

Which option with will easier? docker image vs vanilla install ?
Any advise welcome, before I invest more time into which option to go.

Docker might be easier if we need to do incremental version upgrade should v19 fails.

4

+1 for using Docker. Easier to do testing by just changing the image version number.

5

Here’s my progress so far:

  • installed mysql 8 on server, exported db dump from v10 keycloak and successfully imported into the mysql8.

Next step I plan to follow the info from this:
Running Keycloak in a container - Keycloak

  • build an optimized Keycloak docker image with the db connection config into the dockerfile.
  • go with http only for now

My question now is, do I config the docker(keycloak) to be able to access the db on the server? I assume I need to somehow open 3306 from docker image to access it?

Done some quick research, do I

  1. add config to dockerfile to open up port ?
  2. something with compose-docker.yml ?

Many opinions given:
From inside of a Docker container, how do I connect to the localhost of the machine? - Stack Overflow

Has anyone done it?

6

Progress update:

After many attempt, the docker keycloak fails to connect to the local MYSQL instance, keep getting:
Caused by: java.net.ConnectException: Connection refused (Connection refused)

I’ve now used Docker MYSQL and Docker Keycloak with success.
Here’s a quick summary :slight_smile:

  1. docker network create keycloak-network

  2. docker run -v /opt/docker/volume:/var/lib/mysql -p 3306:3306 --name mysql -d --net keycloak-network -e MYSQL_DATABASE=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD= -e MYSQL_ROOT_PASSWORD= mysql

  3. Import v10 data dump into keycloak schema

  4. docker run -p 80:8080 --name keycloak --net keycloak-network -e KEYCLOAK_ADMIN= -e KEYCLOAK_ADMIN_PASSWORD= -e KC_DB=mysql -e KC_DB_URL=jdbc:mysql://mysql:3306/keycloak -e KC_DB_USERNAME=keycloak -e KC_DB_PASSWORD= Quay start-dev