<#import "/templates/guide.adoc" as tmpl> <#import "/templates/kc.adoc" as kc> <@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. == 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 ` option. <@kc.export parameters="--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 ` 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 --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 ` option. <@kc.export parameters="--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] --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 ` option to import the realm back to the server as follows: <@kc.import parameters="--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 --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 ` option as follows: <@kc.import parameters="--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. Each file in this directory should contain a single realm configuration. If a realm already exists in the server, the import operation is skipped. == Using Environment Variables within the Realm Configuration Files When importing a realm, 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.