Draft of usage instructions for Decoupling on UPS

usage_instructions.md

UPS decoupling instructions

The following scenarios were tested against WildFly 9 and Keycloak 1.7.0.Final/1.8.0.CR3

Scenario 1

Description

The following setup covers scenarios where people wants to deploy Keycloak and UPS in separated Wildfly instances.

Keycloak setup

1. Deploy Keycloak following these instructions
2. Import the realm configuration file and start WildFly in a separate port

$UPS_HOME/bin/keycloak-setup.sh --ups-host=http://localhost:8082 --wildfly-offset=3 --realm-import=$UPS_HOME/bin/ups-realm-template.json

3. Keycloak server should start with aerogear realm imported

UPS setup

1. Follow the setup instructions described here.

2. Setup the Keycloak subsystem

  $UPS_HOME/bin/ups-setup.sh --subsystem-setup

3. Start WildFly in a separate port

$WILDFLY_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=2 --server-config=standalone-full.xml

4. Setup UPS instance to properly be attached to Keycloak instance

$UPS_HOME/bin/ups-setup.sh --ups-host=localhost:9992 --realm=aerogear --auth-server=http://localhost:8083

5. Deploy the UnifiedPush server

Scenario 2

Description

The following setup covers scenarios where people wants to have multiple WildFly instances of UPS authenticating against just one server running Keycloak.

One Keycloak instance, multiple UnifiedPush servers

Keycloak setup

1. Deploy Keycloak following these instructions

2. Create the realm configuration file or just copy from UPS template

cp ups-realm-template.json ups-production-realm.json
cp ups-realm-template.json ups-dev-realm.json

3. Change the realm name

For example, at ups-dev-realm.json change "realm": "aerogear" to "realm": "aerogear-dev".

4. Import the realm configuration file and start WildFly in a separate port

$UPS_HOME/bin/keycloak-setup.sh --ups-host=http://localhost:8081,http://localhost:8082 --wildfly-offset=3 --realm-import=$UPS_HOME/bin/ups-dev-realm.json,$UPS_HOME/bin/ups-production-realm.json

UPS setup

1. Follow the setup instructions described here.

2. Setup the Keycloak subsystem

Under WildFly development instance

  $UPS_HOME/bin/ups-setup.sh --subsystem-setup

Under WildFly production instance

  $UPS_HOME/bin/ups-setup.sh --subsystem-setup

3. Setup UPS instance to properly be attached to Keycloak instance

Under WildFly development instance

$UPS_HOME/bin/ups-setup.sh --ups-host=localhost:9991 --realm=aerogear-dev --auth-server=http://localhost:8083

Under WildFly production instance

$UPS_HOME/bin/ups-setup.sh --ups-host=localhost:9992 --realm=aerogear-production --auth-server=http://localhost:8083

5. Deploy the UnifiedPush server

Deploying in an already existent realm

Description

The following scenarios applies for sittuations where people already have Keycloak deployed and want to have all the setup in a single realm.

Note

This is only available on Keycloak 1.8.x.

Keycloak setup

1. Deploy Keycloak following these instructions

2. Visit http://yourhost/auth/

3. Setup username and password

4. Open the Realm template located at $UPS_HOME/bin and replace dummyhost, by your host.

5. Import users, clients and roles with Partial import

UPS setup

1. Follow the setup instructions described here.

2. Setup the Keycloak subsystem

  $UPS_HOME/bin/ups-setup.sh --subsystem-setup

3. Start WildFly in a separate port

$WILDFLY_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=2 --server-config=standalone-full.xml

4. Setup UPS instance to properly be attached to Keycloak instance

$UPS_HOME/bin/ups-setup.sh --ups-host=localhost:9992 --realm=master --auth-server=http://localhost:8083

5. Deploy the UnifiedPush server