Keycloak in Docker #6 – How to import realms from a directory

If we want to import multiple Keycloak realms, or realm resources are split into multiple files, we need to execute a directory import at boot time. Fortunately, running a Keycloak service with Docker makes this task easy.

Prerequsites

• Docker Engine and Docker Compose installed on your machine.
• If this is your first attempt to run Keycloak in Docker, I recommend reading the post Keycloak in Docker # 1 – How to run Keycloak in a Docker container, as I explained the basic configuration there.
• You’ll need at least one realm that was exported to a directory. You can learn how to do it in the Keycloak in Docker #5 – How to export a realm with users and secrets post.

Configure importing Keycloak relams from a directory

The example Docker Compose configuration used below is available in the https://gist.github.com/little-pinecone/6b52ccd1fc0296b267e810d43fd01f3b GitHub gist.

The importance of the naming convention

As we can read in the docs:

When importing from a directory, the filenames must follow this naming convention:

<REALM_NAME>-realm.json. For example, “acme-roadrunner-affairs-realm.json” for the realm named “acme-roadrunner-affairs”.

<REALM_NAME>-users-<INDEX>.json. For example, “acme-roadrunner-affairs-users-0.json” for the first user’s file of the realm named “acme-roadrunner-affairs”.

https://www.keycloak.org/docs/16.1/server_admin/#assembly-exporting-importing_server_administration_guide

Make sure the resources for your realms follow this naming convention. Otherwise, some or all of the files may be skipped completely from import.

Add a Docker volume for the imported resources

First, I’m going to create a Docker volume to make the import assets available in the /tmp/import directory in the container. Below you’ll find the relevant configuration from my docker-compose.yml file:

version: '3.3'
services:
  keycloak:
    …
    volumes:
      - ./keycloak/realms/import:/tmp/import
    …

Provide the required options when running the container

Next, I’m going to add the minimum configuration required to perform the directory import to my docker-compose.yml file:

services:
  keycloak:
    …
    volumes:
       …
    command:
      - "-Dkeycloak.migration.action=import"
      - "-Dkeycloak.migration.provider=dir"
      - "-Dkeycloak.migration.dir=/tmp/import"

This configuration will overwrite existing realms by default. For other keycloak.migration.X options, see the official Keycloak documentation on importing and exporting the database.

Import a Keycloak realm that has been exported in multiple files

Below you can see the starting point for importing my keep-growing realm:

To summarize, I have one file with the realm configuration and one with the associated users. With the Docker Compose configuration described in the previous section, I’m going to start the container using the docker-compose up -d command.

As a result, we can see in the screenshot below that the volume with realm resources was mapped properly:

Furthermore, the container logs contain entries documenting a successful import:

INFO  [org.keycloak.exportimport.dir.DirImportProvider] (ServerService Thread Pool -- 62) Importing from directory /tmp/import
…
INFO  [org.keycloak.services] (ServerService Thread Pool -- 62) KC-SERVICES0050: Initializing master realm
INFO  [org.keycloak.services] (ServerService Thread Pool -- 56) KC-SERVICES0030: Full model import requested. Strategy: OVERWRITE_EXISTING
INFO  [org.keycloak.exportimport.util.ImportUtils] (ServerService Thread Pool -- 56) Realm 'keep-growing' imported
INFO  [org.keycloak.exportimport.dir.DirImportProvider] (ServerService Thread Pool -- 56) Imported users from /tmp/import/keep-growing-users-0.json
INFO  [org.keycloak.services] (ServerService Thread Pool -- 56) KC-SERVICES0032: Import finished successfully

At last, we can examine the imported realm in the Keycloak Admin Console:

Import multiple Keycloak realms

Below you can see the starting point for importing my keep-growing and Example-Realm realms:

To summarize, I have two files, one for each realm. With the Docker Compose configuration described in the previous section, I’m going to start the container using the docker-compose up -d command.

Consequently, we can see in the screenshot below that the volume with realms is available in the container:

Furthermore, the container logs contain entries documenting successful imports:

INFO  [org.keycloak.exportimport.dir.DirImportProvider] (ServerService Thread Pool -- 62) Importing from directory /tmp/import
…
INFO  [org.keycloak.services] (ServerService Thread Pool -- 62) KC-SERVICES0050: Initializing master realm
INFO  [org.keycloak.services] (ServerService Thread Pool -- 62) KC-SERVICES0030: Full model import requested. Strategy: OVERWRITE_EXISTING
INFO  [org.keycloak.exportimport.util.ImportUtils] (ServerService Thread Pool -- 62) Realm 'keep-growing' imported
INFO  [org.keycloak.exportimport.util.ImportUtils] (ServerService Thread Pool -- 62) Realm 'Example-Realm' imported
INFO  [org.keycloak.services] (ServerService Thread Pool -- 62) KC-SERVICES0032: Import finished successfully

Finally, we can examine the imported realm in the Keycloak Admin Console:

Read more on Keycloak directory import

• In addition to this article, see the Keycloak documentation on importing and exporting the database.
• Additionally, you can visit the How to import Multiple realms in keycloak? and Missing users from Keycloak Realm after import issues on StackOverflow.
• In case you need to import realm from a single file, see the Keycloak in Docker #2 – How to import a Keycloak realm post.

Photo by Vlada Karpovich from Pexels