Docker Installation#

Overview#

This guide provides instructions for deploying the Gluu Server on a single node VM using Docker.

Prerequisites#

For Docker deployments, provision a VM with:

Linux users#

The minimum system requirements, as described in the VM Preparation Guide.
Docker is installed

Mac users#

The minimum system requirements for Docker for Mac
Docker Desktop for Mac

Instructions#

Obtain files for deployment#

Download the latest pygluu-compose-linux-amd64.pyz (or pygluu-compose-macos-amd64.pyz for Mac users) file from Releases page and save it as pygluu-compose.pyz.

Note

pygluu-compose.pyz requires Python 3.6+ (and python3-distutils package if Ubuntu/Debian is used).

Make sure to set the downloaded pygluu-compose.pyz file as executable:

chmod +x pygluu-compose.pyz

Run the following command to generate manifests for deployment:

./pygluu-compose.pyz init

The generated files are similar to example below:

tree .
.
├── couchbase.crt
├── couchbase_password
├── couchbase_superuser_password
├── docker-compose.yml
├── gcp_kms_creds.json
├── gcp_kms_stanza.hcl
├── jackrabbit_admin_password
├── job.persistence.yml
├── pygluu-compose.pyz
├── svc.casa.yml
├── svc.cr_rotate.yml
├── svc.fido2.yml
├── svc.jackrabbit.yml
├── svc.ldap.yml
├── svc.oxauth.yml
├── svc.oxd_server.yml
├── svc.oxpassport.yml
├── svc.oxshibboleth.yml
├── svc.oxtrust.yml
├── svc.radius.yml
├── svc.redis.yml
├── svc.scim.yml
├── svc.vault_autounseal.yml
├── vault_gluu_policy.hcl
├── vault_role_id.txt
└── vault_secret_id.txt

Proceed to deployment section for basic setup of Gluu Server deployment or read the customizing section for advance setup.

Customizing installation#

Choose services#

The following services are available during deployment:

Service	Setting Name	Mandatory	Enabled by default
`consul`	-	yes	always
`registrator`	-	yes	always
`vault`	-	yes	always
`nginx`	-	yes	always
`persistence`	`JOB_PERSISTENCE`	no	yes
`oxauth`	`SVC_OXAUTH`	no	yes
`oxtrust`	`SVC_OXTRUST`	no	yes
`ldap`	`SVC_LDAP`	no	yes
`oxpassport`	`SVC_OXPASSPORT`	no	no
`oxshibboleth`	`SVC_OXSHIBBOLETH`	no	no
`redis`	`SVC_REDIS`	no	no
`radius`	`SVC_RADIUS`	no	no
`vault` auto-unseal	`SVC_VAULT_AUTOUNSEAL`	no	no
`oxd_server`	`SVC_OXD_SERVER`	no	no
`cr_rotate`	`SVC_CR_ROTATE`	no	no
`casa`	`SVC_CASA`	no	no
`scim`	`SVC_SCIM`	no	no
`fido2`	`SVC_FIDO2`	no	no
`jackrabbit`	`SVC_JACKRABBIT`	no	no

To enable/disable non-mandatory services listed above, create a file called settings.py and set the value to True to enable or set to False to disable the service. For example:

# enable ldap service
SVC_LDAP = True

# disable passport service
SVC_OXPASSPORT = False

Any services not specified in settings.py will follow the default settings.

To override manifests (i.e. changing oxAuth service definition), add ENABLE_OVERRIDE = True in settings.py, for example:

ENABLE_OVERRIDE = True

Then define overrides in docker-compose.override.yml (create the file if not exist):

version: "2.4"

services:
  oxauth:
    container_name: my-oxauth

If docker-compose.override.yml exists, this file will be added as the last Compose file. For reference on multiple Compose file, please take a look at https://docs.docker.com/compose/extends/#multiple-compose-files.

Choose persistence backends#

Supported backends are LDAP, Couchbase, or mix of both (hybrid). The following config control which persistence backend is selected:

PERSISTENCE_TYPE: choose one of ldap, couchbase, or hybrid (the default is ldap)
PERSISTENCE_LDAP_MAPPING: choose one of default, user, site, cache, token, or session (default to default)

To choose a persistence backend, create a file called settings.py (if it wasn't created in the last step) and set the corresponding option as seen above. For example:

# Couchbase will be selected
PERSISTENCE_TYPE = "couchbase"

# store user mapping in LDAP
PERSISTENCE_LDAP_MAPPING = "user"

# Couchbase user (has access to read and write data, read buckets, etc)
COUCHBASE_USER = "admin"

# optional, Couchbase superuser (has access to create buckets, etc)
COUCHBASE_SUPERUSER = ""

# Couchbase bucket prefix
COUCHBASE_BUCKET_PREFIX = "gluu"

# Host/IP address of Couchbase server; omit the port
COUCHBASE_URL = "192.168.100.4"

If couchbase or hybrid is selected, there are additional steps required to satisfy dependencies:

put Couchbase cluster certificate into the couchbase.crt file
put Couchbase password into the couchbase_password file
the Couchbase cluster must have data, index, and query services at minimum
if COUCHBASE_URL is set to hostname, make sure it can be reached by DNS query; alternatively add the extra host into docker-compose.override.yml file, for example:
```
services:
  oxauth:
    extra_hosts:
    - "${COUCHBASE_HOSTNAME}:${COUCHBASE_IP}"
```

Set up Vault auto-unseal#

Enable Vault auto-unseal with GCP KMS API by specifying it in settings.py:

# settings.py

# enable Vault auto-unseal with GCP KMS API
SVC_VAULT_AUTOUNSEAL = True

The following is an example of how to obtain GCP KMS credentials JSON file, and save it as gcp_kms_creds.json in the same directory where pygluu-compose.pyz is located, for example:

{
    "type": "service_account",
    "project_id": "project",
    "private_key_id": "1234abcd",
    "private_key": "-----BEGIN PRIVATE KEY-----\nabcdEFGH==\n-----END PRIVATE KEY-----\n",
    "client_email": "sa@project.iam.gserviceaccount.com",
    "client_id": "1234567890",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/sa%40project.iam.gserviceaccount.com"
}

Afterwards, create gcp_kms_stanza.hcl in the same directory where pygluu-compose.pyz is located; for example:

seal "gcpckms" {
    credentials = "/vault/config/creds.json"
    project     = "vault-project-1234"
    region      = "us-east1"
    key_ring    = "vault-keyring"
    crypto_key  = "vault-key"
}

Note

Adjust the contents of gcp_kms_stanza.hcl except the credentials value as it is mapped in svc.vault_autounseal.yml file.

Choose Document Storage#

There are 2 types of supported document storage:

LOCAL

This is the default document store (using container's filesystem).
JCA

This document store uses jackrabbit service. To enable JCA document store, modify settings.py as seen below:
```
SVC_JACKRABBIT = True
DOCUMENT_STORE_TYPE = "JCA"
```
By default jackrabbit service will add its own user/password credentials (default to admin username and admin password). To change the credentials, add the following config in settings.py:
```
# change the username
JACKRABBIT_USER = "my-jackrabbit-user"
```
Modify jackrabbit_admin_password file:
```
my-jackrabbit-password
```
If somehow users need to modify the credentials after service is running, there are few steps need to be done:
- change credentials via oxTrust UI (Configuration > JSON Configuration > Store Provider Configuration menu).
  - adjust the User Id form field
  - adjust the Password form field (use plaintext password, i.e. my-jackrabbit-password)
  - submit the form
- change JACKRABBIT_USER config in settings.py
- change the password in jackrabbit_admin_password file
- re-deploy oxtrust and jackrabbit services

Cache Refresh IP Rotation#

Configuring LDAP Synchronization (Cache Refresh) requires static IP address of oxTrust, but in container world, the IP address is assigned dynamically.

By enabling cr_rotate service, the required IP address of oxTrust can be discovered and configured in persistence:

# enable cache refresh IP rotation
SVC_CR_ROTATE = True

Note that users still need to enable and configure Cache Refresh.