Docker Setup for the Keycloak instance of the "Center for Research Data management". This keycloak service maintains a
separate realm for the main and the test instance of invenio.
Docker Setup for the Keycloak instance of the "Center for Research Data Management". The keycloak service maintains separate realms for the main (tu-data realm) and the test instance (tu-data-test realm) of TU Wien Research Data. Further information about Keycloak can be found in the [official documentation](https://www.keycloak.org/documentation).
# Exportin Realms
To export all realms of the keycloak instance the lines 52-54 have to be uncommented in the docker-compose file. After
restarting (`docker-compose down && docker-compose up -d`) keycloak all realms are exported to `export/realms-export.json`.
**IMPORTANT:** make sure that the keycloak container is allowed to write into the export directory!
## Secrets and Configuration
We all keep secrets.
Similarly, some things such as passwords should be kept secret when deploying in production!
For this reason, we use *environment variables* to store the confidential parts of our configuration. Since exporting the correct environment variables manually every time can be very tedious, we use `.env` files.
# Importing Realms
To import realms into a new keycloak instance first place your dump file (`realms-export.json`) into the export folder.
Next, execute the `import-realms.sh` script which erases all existing data on the keycloak instance and then imports the
provided realm-dump.
To quickly spin up a development instance, the current setup can handle the absence of a `.env` file by using fallback values provided in the `docker-compose.yml` file. These fallbacks will take care of giving the environment variables appropriate values. As mentioned above however, there are environment variables holding sensitive data (e.g. database password) and thus these fallbacks **SHOULD NOT** be used in a production setting.
----------------------------------------
Furhter Information about Import/Export can be found in the [official documentation](https://wjw465150.gitbooks.io/keycloak-documentation/content/server_admin/topics/export-import.html)
\ No newline at end of file
### Example Secrets File
An example `.env` file is available as [`.example.env`](./.example.env). Its goal is to give a rough overview of what the environment variables and their values should look like.
After copying the file (`cp .example.env .env`) and replacing the dummy values, it is ready for use. Yet again, **DO NOT** use these values in production; they are embrassingly simple!
## Performing a Keycloak Realm(s) Export/Import
The primary reason to export/import realms is simple: keep a backup of the current setting. With this feature, we can back up the current keycloak data and restore them whenever required. Better safe than sorry!
### Exporting Realms
Exporting one or multiple realms is important, in case backups or data transfer between servers is needed. The [export-realms.sh](./scripts/export-realms.sh) script is responsible for dumping all the realms in a JSON file.
The Keycloak Admin Console offers also an easy way to export realms. So why not use that instead? Because the export file won't contain any user data. Besides that, the client secrets will be masked, which means that we won't be able to recreate the same exact instance using only this file.
#### Brief explanation of the arguments used for exporting realms
*`-Djboss.socket.binding.port-offset`
Specifies port offset which this action will use. We want to run the export on a different port than Keycloak itself. By default, the jboss server in the current setup uses the 9990 port. Therefore, providing e.g. 100 as a value here will result in the command using the 10090 port.
*`-Dkeycloak.migration.action`
Specifies what action should be taken, export or import.
*`-Dkeycloak.migration.provider`
Defines how we want the data. We use `singleFile`, to export all the data into a single file.
*`-Dkeycloak.migration.usersExportStrategy`
Specifies the strategy to export realm users. We use `REALM_FILE` to export the users to the same file as the realm configuration.
*`-Dkeycloak.migration.file`
Defines the file where we want to save the data. Remember to prepend to the filename the exact same value that is used for the volume mapping in the `docker-compose.yml`.
### Importing Realms
Having a dockerized Keycloak service that works out of the box and contains an imported realm with its default users is very useful. This not only simplifies the setup process, but also allows us to share a replicable Keycloak instance with others. The [import-realms.sh](./scripts/import-realms.sh) script is responsible for reading and importing all the realms from a JSON file (that was naturally exported from Keycloak itself).
#### Brief explanation of the arguments used for importing realms
*`-Djboss.socket.binding.port-offset`
Specifies port offset which this action will use. We want to run the import on a different port than Keycloak itself. By default, the jboss server in the current setup uses the 9990 port. Therefore, providing e.g. 10 as a value here will result in the command using the 10000 port.
*`-Dkeycloak.migration.action`
Specifies what action should be taken, export or import.
*`-Dkeycloak.migration.provider`
Defines how we are importing the data. We use `singleFile` to import all the data from a single file.
*`-Dkeycloak.migration.strategy`
Specifies how to proceed when a realm with the same name already exists in the database. We use `IGNORE_EXISTING` to avoid overwriting a realm if it already exists.
*`-Dkeycloak.profile.feature.upload_scripts`
The ability to enable custom scripts at startup. We use `enabled` since we have a logging script.
**Note**: This feature is deprecated and has been removed from version 18.0 and later on.
*`-Dkeycloak.migration.file`
Defines the file which we want to import the data from. Remember to prepend to the filename the exact same value that is used for the volume mapping in the `docker-compose.yml`.
