Configuration¶

Changing default port¶

Usage¶

To change the default port two operations are needed :

1: Update the front-end configuration

OnSphere stack front-end default port is 5000, to change this value update the environnement variable APPLICATION_EXTERNAL_PORT.

2: Update the stack.cfg

See schema of stack.cfg

"frontendPort":000,

Hostname¶

Overview¶

The hostname is required to match the stack outside FQDN name. It is mandatory for Keycloak and proxy to work properly as well as to serve HTTPS content by default.

Its value is used to generate self-signed HTTPS certificate for the front-end or to validate external certificate setup.

Configuring the hostname¶

The hostname is configured in a file named stack.cfg. This file must contain the configuration and contains the hostname key, which will be used as the system hostname.

Currently the stack.cfg can be used by :

All web modules
The Keycloak module
The dispatcher module

A minimal configuration example (to be adapted if you are using more than one frontend, Keycloak or other stuff)

See the example

Warning

If you have multiples web modules, be sure all modules are using the stack.cfg (Add the module id to the moduleId list).

see Set certificate for details for using a certificate.

Set certificate¶

Overview¶

To override SSL setup, you must first deploy secrets to portainer and then configure the certificate and key in the configuration.

Usage¶

Edit front-end module.service file with the following content:

${{service-name}}:

ports:
    - "<port>:5000/tcp"
    - "<port>:5001/tcp"
    ...
environment:
    ...
    - APPLICATION_EXTERNAL_PORT=<port>
    - SSL_CERTIFICATE=/run/secrets/<secret-certificate-filename>
    - SSL_CERTIFICATE_KEY=/run/secrets/<secret-certificate-key-filename>
...
secrets:
    - source: <secret-certificate-filename>
    target: <secret-certificate-filename>
    - source: <secret-certificate-key-filename>
    target: <secret-certificate-key-filename>

Then edit stack.secrets in stack folder with following content :

secrets:
...
<secret-certificate-filename>:
    external: true
<secret-certificate-key-filename>:
    external: true

When updating HTTPS, you have to reflect the changes in web module.web file as follows:

{ ...
    "keycloakConfiguration"
: { ...
        "frontendHostname"
    : "https://<host>:<port>", ... } }

Change token validity duration¶

The token generated upon user connection have a limited validity to avoid them being used by an unauthorized user if stolen.

Note

If you need to have a token valid for more than 12 hours, you need to add the “offline-access” for the user and use the /monitor endpoint when accessing OnSphere. This endpoint is designed for wallboard/monitoring screen access.

Tip

We recommended that user using the offline-access cannot make any action on the stack.

The token needs to be refreshed at most every 30 minutes otherwise the user will need to reconnect. In any case when a user is connected for more than 12 hours, he will need to reconnect.

These parameters are managed inside the realm.json.

Name	Front-end name	Description	Default
ssoSessionIdleTimeout	SSO Session Idle	The maximum validity token time without any activity	1800
ssoSessionMaxLifespan	SSO Session Max	The absolute maximum token lifespan	43200

Note

For testing, you can directly edit these parameters on the admin page “/auth/admin” but changes made this way will be reset when a new Keycloak configuration is applied.

HTTP only¶

Warning

Some browsers may not support some features. We officially do not provide support for functionalities related to HTTP connections in such cases.

Usage¶

If, for any reason, you want to use unsecured HTTP, it is possible. Remove the certificates from the front-end modules services file by removing certificates in the environment variable and push the configuration:

${{service-name}}:
  ...
  ports:
    - "<port>:5000/tcp"
    ...
  environment:
    ...
    - APPLICATION_EXTERNAL_PORT=<port>
    - SSL_CERTIFICATE=
    - SSL_CERTIFICATE_KEY=
  ...