Introduction

Redis is a in-memory data structure store, used as a database, cache and message broker. Onegini uses Redis for cache replication for multiple applications.

For our IDP we use Redis Sentinel. Redis Sentinel provides high availability for Redis. It is based on three boxes, each box running both a Redis process and a Sentinel process.

       +----+
       | M1 |
       | S1 |
       +----+
          |
+----+    |    +----+
| R2 |----+----| R3 |
| S2 |         | S3 |
+----+         +----+

Configuration: quorum = 2 If the master M1 fails, S2 and S3 will agree about the failure and will be able to authorize a failover, making clients able to continue.

Setup

This guide walks you through the process of Onegini IDP setup.

To download the containers you first need to login with the Docker client using your login credentials.

$ docker login release.onegini.com

NOTE: If you did not not receive any login credentials, please contact Onegini Support.

Redis

Recommended setup (master/slave/slave)

Host 1: master and sentinel

Host 2: slave and sentinel

Host 3: slave and sentinel

On every host there should be a docker-compose.yml file.

Examples

`docker-compose.yml` Host 1

master:
  image: release.onegini.com/onegini/redis:1.0.0
  user: onegini
  environment:
    - REDIS_PORT=6379
    - REDIS_ANNOUNCE_IP=<IP HOST 1>
    - REDIS_ANNOUNCE_PORT=6379
  ports:
    - 6379:6379

sentinel:
  image: release.onegini.com/onegini/redis:1.0.0
  user: onegini
  environment:
    - REDIS_SENTINEL=True
    - REDIS_SENTINEL_PORT=5000
    - REDIS_SENTINEL_ANNOUNCE_IP=<IP HOST 1>
    - REDIS_SENTINEL_ANNOUNCE_PORT=5000
    - REDIS_SENTINEL_MASTER_IP=<IP HOST 1>
    - REDIS_SENTINEL_MASTER_PORT=6379
  ports:
    - 5000:5000

`docker-compose.yml` Host 2

slave:
  image: release.onegini.com/onegini/redis:1.0.0
  user: onegini
  environment:
    - REDIS_PORT=6379
    - REDIS_ANNOUNCE_IP=<IP HOST 2>
    - REDIS_ANNOUNCE_PORT=6379
    - REDIS_SLAVE=True
    - REDIS_SLAVEOF_IP=<IP HOST 1>
    - REDIS_SLAVEOF_PORT=6379
  ports:
    - 6379:6379

sentinel:
  image: release.onegini.com/onegini/redis:1.0.0
  user: onegini
  environment:
    - REDIS_SENTINEL=True
    - REDIS_SENTINEL_PORT=5000
    - REDIS_SENTINEL_ANNOUNCE_IP=<IP HOST 2>
    - REDIS_SENTINEL_ANNOUNCE_PORT=5000
    - REDIS_SENTINEL_MASTER_IP=<IP HOST 1>
    - REDIS_SENTINEL_MASTER_PORT=6379
  ports:
    - 5000:5000

`docker-compose.yml` Host 3

slave:
  image: release.onegini.com/onegini/redis:1.0.0
  user: onegini
  environment:
    - REDIS_PORT=6379
    - REDIS_ANNOUNCE_IP=<IP HOST 3>
    - REDIS_ANNOUNCE_PORT=6379
    - REDIS_SLAVE=True
    - REDIS_SLAVEOF_IP=<IP HOST 1>
    - REDIS_SLAVEOF_PORT=6379
  ports:
    - 6379:6379

sentinel:
  image: release.onegini.com/onegini/redis:1.0.0
  user: onegini
  environment:
    - REDIS_SENTINEL=True
    - REDIS_SENTINEL_PORT=5000
    - REDIS_SENTINEL_ANNOUNCE_IP=<IP HOST 3>
    - REDIS_SENTINEL_ANNOUNCE_PORT=5000
    - REDIS_SENTINEL_MASTER_IP=<IP HOST 1>
    - REDIS_SENTINEL_MASTER_PORT=6379
  ports:
    - 5000:5000

Configure Redis via Docker Compose environment variables

The Redis environment uses Docker Compose environment variables to manage application properties. You can find all properties below per node.

Master:

Environment variable	Example	Description
REDIS_PORT=	6379	Redis port number
REDIS_ANNOUNCE_IP=	172.17.0.1	IP address of host
REDIS_ANNOUNCE_PORT=	6379	Announce port on host

Slave:

Environment variable	Example	Description
REDIS_PORT=	6379	Redis port number
REDIS_ANNOUNCE_IP=	172.17.0.2	IP address of host
REDIS_ANNOUNCE_PORT=	6379	Announce port
REDIS_SLAVE=	True	Set slave to `true` or `false`
REDIS_SLAVEOF_IP=	172.17.0.1	IP address of master
REDIS_SLAVEOF_PORT=	6379	Port number of master

Sentinel:

Environment variable	Example	Description
REDIS_SENTINEL=	True	Set sentinel to `true` or `false`
REDIS_SENTINEL_PORT=	5000	Sentinel port number host
REDIS_SENTINEL_ANNOUNCE_IP=	172.17.0.1	IP address of host
REDIS_SENTINEL_ANNOUNCE_PORT=	5000	Sentinel announce port host
REDIS_SENTINEL_MASTER_IP=	172.17.0.1	IP address of master
REDIS_SENTINEL_MASTER_PORT=	6379	Port number of master

Start Redis environment

Host 1: $ docker-compose -f /opt/onegini/redis/docker-compose.yml up

Host 2: $ docker-compose -f /opt/onegini/redis/docker-compose.yml up

Host 3: $ docker-compose -f /opt/onegini/redis/docker-compose.yml up

Verify if Redis is started successfully

$ docker ps

Output on host 1 should something like this:

9661ddca3af6    release.onegini.com/onegini/redis:1.0.0    "/usr/bin/dumb-ini..."    2 hours ago     Up 32 minutes     0.0.0.0:6379->6379/tcp     redis_master_1
cbef577d2afb    release.onegini.com/onegini/redis:1.0.0    "/usr/bin/dumb-ini..."    2 hours ago     Up 32 minutes     0.0.0.0:5000->5000/tcp     redis_sentinel_1

Test failover

Start onscreen logging: $ docker-compose -f /opt/onegini/redis/docker-compose.yml logs

Now open a new terminal on host 2 and stop the master node on host 1:

$ docker stop redis_master_1

On host 2 there should be an event stating something like this:

slave_1 | 8:M 12 Apr 13:11:35.977 * MASTER MODE enabled ...

This should happen in about 5 seconds from stopping de master node.

When starting the master, it becomes the slave since the initial slave has become master.

Install Onegini IDP

There are two ways of installing Onegini IDP.

Docker Index

The first and preferred way is to use the Onegini index. This is the central container repository of Onegini.

After you logged in to the Onegini Index you can pull the latest images.

docker pull release.onegini.com/onegini/idp-generic:<VERSION>
docker pull release.onegini.com/onegini/idp:<VERSION>

where <VERSION> can be set to concrete version or latest to use newest one.

NOTE: If you did not not receive any login credentials, please contact Onegini support.

Import from tar

The second way is to import the image from tar. This options is mostly used when the docker host has no internet connection.

docker load < /path/to/idp-generic-<version>.tar
docker load < /path/to/idp-<version>.tar

Show images

To verify that the docker images are loaded use the docker images command.

docker images

Download configuration files

To configure Onegini IDP please download compressed tar file, extract it to some directory and edit idp-extension-general.env by changing these properties:

IDP_HOST_URL
IDP_DATABASE_URL
IDP_DATABASE_USER
IDP_DATABASE_PASSWORD
IDP_SMTP_HOST
IDP_SMTP_PORT

For more configuration go to the properties section.

Start docker containers

Start docker containers by executing this command:

docker-compose -f <directory with extracted files>/docker-compose.yml up -d

Command will stop, remove existing / old containers and start new containers at the same time. For more information see the Docker Compose documentation.

Log in to the application

After starting the application it will be accessible via these addresses:

Admin panel: <DOCKER_HOST>:8992/admin
IDP login page: <DOCKER_HOST>:8990

where <DOCKER_HOST> is the IP ddress of the machine where docker is running on.