keycloak-scim/docs/guides/server/importExport.adoc

<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>
<#import "/templates/links.adoc" as links>

<@tmpl.guide
    title="Importing and Exporting Realms"
    summary="An overview about how to import and export realms">

In this guide, you are going to understand the different approaches for importing and exporting realms using JSON files.

== Providing options for database connection parameters

When using the `export` and the `import` commands below, Keycloak needs to know how to connect to the database where the information about realms, clients, users and other entities is stored.
As described in <@links.server id="configuration"/> that information can be provided as command line parameters, environment variables or a configuration file.
Use the `--help` command line option for each command to see the available options.

Some of the configuration options are build time configuration options.
As default, Keycloak will re-build automatically for the `export` and `import` commands if it detects a change of a build time parameter.

If you have built an optimized version of Keycloak with the `build` command as outlined in <@links.server id="configuration"/>, use the command line option `--optimized` to have Keycloak skip the build check for a faster startup time.
When doing this, remove the build time options from the command line and keep only the runtime options.

== Exporting a Realm to a Directory

To export a realm, you can use the `export` command. Your Keycloak server instance must not be started when invoking this command.

<@kc.export parameters="--help"/>

To export a realm to a directory, you can use the `--dir <dir>` option.

<@kc.export parameters="--dir <dir>"/>

When exporting realms to a directory, the server is going to create separate files for each realm being exported.

=== Configuring how users are exported

You are also able to configure how users are going to be exported by setting the `--users <strategy>` option. The values available for this
option are:

* *different_files*: Users export into different json files, depending on the maximum number of users per file set by `--users-per-file`. This is the default value.

* *skip*: Skips exporting users.

* *realm_file*:  Users will be exported to the same file as the realm settings. For a realm named "foo", this would be "foo-realm.json" with realm data and users.

* *same_file*:  All users are exported to one explicit file. So you will get two json files for a realm, one with realm data and one with users.

If you are exporting users using the `different_files` strategy, you can set how many users per file you want by setting the `--users-per-file` option. The default value is `50`.

<@kc.export parameters="--dir <dir> --users different_files --users-per-file 100"/>

== Exporting a Realm to a File

To export a realm to a file, you can use the `--file <file>` option.

<@kc.export parameters="--file <file>"/>

When exporting realms to a file, the server is going to use the same file to store the configuration for all the realms being exported.

== Exporting a specific realm

If you do not specify a specific realm to export, all realms are exported. To export a single realm, you can use the `--realm` option as follows:

<@kc.export parameters="[--dir|--file] <path> --realm my-realm"/>

== Importing a Realm from a Directory

To import a realm, you can use the `import` command. Your Keycloak server instance must not be started when invoking this command.

<@kc.import parameters="--help"/>

After exporting a realm to a directory, you can use the `--dir <dir>` option to import the realm back to the server as follows:

<@kc.import parameters="--dir <dir>"/>

When importing realms using the `import` command, you are able to set if existing realms should be skipped, or if they should be overridden with the new configuration. For that,
you can set the `--override` option as follows:

<@kc.import parameters="--dir <dir> --override false"/>

By default, the `--override` option is set to `true` so that realms are always overridden with the new configuration.

== Importing a Realm from a File

To import a realm previously exported in a single file, you can use the `--file <file>` option as follows:

<@kc.import parameters="--file <file>"/>

== Importing a Realm during Startup

You are also able to import realms when the server is starting by using the `--import-realm` option.

<@kc.start parameters="--import-realm"/>

When you set the `--import-realm` option, the server is going to try to import any realm configuration file from the `data/import` directory. Only regular files using the `.json` extension are read from this directory, sub-directories are ignored.

NOTE: For the https://quay.io/keycloak/keycloak[published containers], the import directory is `/opt/keycloak/data/import`

If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating
realms and potentially loose state between server restarts.

To re-create realms you should explicitly run the `import` command prior to starting the server.

Importing the `master` realm is not supported because as it is a very sensitive operation.

=== Using Environment Variables within the Realm Configuration Files

When importing a realm at startup, you are able to use placeholders to resolve values from environment variables for any realm configuration.

.Realm configuration using placeholders
[source, bash]
----
{
    "realm": "${r"${MY_REALM_NAME}"}",
    "enabled": true,
    ...
}
----

In the example above, the value set to the `MY_REALM_NAME` environment variable is going to be used to set the `realm` property.

</@tmpl.guide>