====== Upgrading Keycloak ======

===== 1. Export realm from existing installation =====

Start your existing ("old") keycloak instance with following parameters: 
<code bash>
bin/standalone.sh -Dkeycloak.migration.action=export -Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=/home/kalaschnikow/Desktop/keycloak.json
</code>

See also [[https://keycloak.gitbooks.io/server-adminstration-guide/content/topics/export-import.html|official documentation]]

===== 2. Install new Keycloak =====
==== 2.1 Download and unzip ====

http://www.keycloak.org/downloads.html

Note: Downloads don't work in Opera (strange...) - 
browser crashes. So it will be better to use Firefox.

==== 2.2 Create a DB ====
It is not recommended to use the built-in H2 database, so we should create a MySQL database for keycloak.

Start mysql
<code bash>
# mysql -u root
</code>

Then create the DB:
<code sql>
create database keycloak2_5_1;
</code>
Then copy the MySQL module to the keycloak. It should be in the directory:\\ 
''$KEYCLOAK_HOME/modules/system/layers/base/com/mysql/jdbc/main''

You can also create this module manually. Here is the [[https://keycloak.gitbooks.io/server-installation-and-configuration/content/topics/database.html|documentation]] about it.

After that edit standalone.xml and add to it the follwing lines:
<code xml>
<subsystem xmlns="urn:jboss:domain:datasources:4.0">
  <datasources>
<!-- ... -->
    <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
      <connection-url>jdbc:mysql://localhost:3306/keycloak2_5_1?useUnicode=true&amp;connectionCollation=utf8_general_ci&amp;characterSetResults=utf8&amp;characterEncoding=utf8</connection-url>
      <driver>mysql</driver>
      <security>
        <user-name>root</user-name>
        <password>YOURPASSWORD</password>
      </security>
    </datasource>
<!-- ... -->
    <drivers>
<!-- ... -->
      <driver name="mysql" module="com.mysql.jdbc">
        <driver-class>com.mysql.jdbc.Driver</driver-class>
        <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
      </driver>
    </drivers>
  </datasources>
</code>

==== 2.3 Create realm and import data====

Start your new Keycloak. Create a new realm. Change into it. Import JSON file. Keycloak should import all users and roles. On "Login" tab set "Require SSL" to "None".

==== 2.4 Create clients ====
=== 2.4.1 avril-web ===
Create client 'avril-web'. Important: Web-Origin should contain "http://localhost:8080/*"

=== 2.4.2 avril-backend ===
Create client 'avril-backend'.

=== 2.4.3 avril-third-party ===
Create client 'avril-third-party'. Valid redirect URIs should contain: 
<code>org.aerogear.Shoot://oauth2Callback</code>

Direct Access Grant Enabled - Off (?). 
On "Scopes" tab: Assigned roles should contain "user".

===== Misc =====

User ''user_manager'' should be existing in realm ''avril-realm'' and should have role ''admin''.