New Installation

This chapter explains how to perform a new installation of Portal Server.

1. Start the docker container. Replace <url> with the public URL intended for the server.

   Windows cmd:

   docker run ^
       --name=simian-portal-server ^
       --env=SIMIAN_PORTAL_EXTERNAL_URL=https://<url> ^
       -p 443:443 ^
       -p 80:80 ^
       -d docker-registry.monkeyproof.lan/simian-portal:latest
   

   Linux bash:

   docker run \
       --name=simian-portal-server \
       --env=SIMIAN_PORTAL_EXTERNAL_URL=https://<url> \
       -p 443:443 \
       -p 80:80 \
       -d docker-registry.monkeyproof.lan/simian-portal:latest
   

2. Verify that the server is running by opening a browser and navigating to https://<url>.

   1. You will probably get a security warning because the HTTPS certificate cannot be validated. Accept the risk and continue.
   2. The login page should now be shown. Log in with username admin and password admin.

Configuration

The Simian Portal server can be configured using environment variables that can be specified as arguments of the docker run command using the --env flag.

See https://docs.docker.com for more information on specifying environment variables in Docker.

Nginx

The default Nginx configuration, runs a HTTPS webserver with a generated openssl certificate. To provide your own certificate, mount it at /etc/nginx/ssl/simian_suite_portal.crt (see Volume Mappings).

PHP

Generic

Authentication Modes

The portal currently supports four authentication modes that can be selected by setting SIMIAN_PORTAL_AUTH_TYPE. The four modes are:

1. anonymous: Anonymous mode allows users to use the portal and applications without authentication. When a session expires it cannot be restored and data may be lost.
2. managed: Basic user management included in the portal. See Managed.
3. ldap: Authentication against Microsoft Active Directory. See LDAP.
4. azure_ad: Authentication against Azure Active Directory. See Azure AD.

Anonymous

Anonymous mode allows access to every user without authentication. Set SIMIAN_PORTAL_AUTH_TYPE to anonymous to enable anonymous mode.

Note: Anonymous mode is for testing purposes only. It should not be used in production.

Managed

The managed mode provides basic stand-alone user management in the admin portal. Users can be created, added to groups in the admin portal and can be invited via email.

Set SIMIAN_PORTAL_AUTH_TYPE to managed to enable managed mode.

To store the groups and users configurations in a permanent location (outside the docker container), mount a folder at /var/simian_portal/config/users (see Volume Mappings).

In order to send the invitation emails, PHPMailer must be configured using the settings SIMIAN_MAIL_*, or by providing a custom PHPMailer configuration file (see Advanced).

Users in the admin group have access to the Admin Portal. To aid initial configuration a user admin with password admin is available in the default configuration. It is recommended to invite yourself as member of the admin group and after successful login remove the default admin user.

Note: reset_admin_password.php allows all users to reset the admin password. Do not forget to disable after use.

LDAP

The Portal Server can be configured to authenticate against Microsoft Active Directory. LDAP integration is enabled by setting the SIMIAN_PORTAL_AUTH_TYPE to ldap.

The connection with the LDAP server is set up using the standard PHP LDAP plugin and can be configured using the settings in the table below.

The default configuration has TLS enabled for secure communications. Mount the Certificate Authority file in /var/simian_portal/config/certs/ca-cert.crt such that the certificate of the LDAP server can be validated (see Volume Mappings).

In case a more advanced LDAP options are required, a custom config.php is needed to provide them (see Advanced). More information about configuring the PHP LDAP plugin can be found here https://www.php.net/manual/en/ldap.constants.php.

Azure AD

The Azure AD authorization mode allows users to authenticate using their Microsoft Azure AD account. When the user is already signed in, the authorization happens without user interaction. Otherwise, the user is redirected to the Microsoft login page.

Azure integration is enabled by setting the SIMIAN_PORTAL_AUTH_TYPE to azure_ad.

Volume Mappings

Volume mappings can be used to (persistently) store files outside the Docker container. This has multiple advantages:

• Settings are available for back-up.
• Settings persist when upgrading the Simian Portal server to a newer version.

Volume mappings can be specified using the --volume flag of the docker command.

The -v or --volume option consists of three fields, separated by colon characters (:). The fields must be in the correct order, and the meaning of each field is not immediately obvious.

• In the case of named volumes, the first field is the name of the volume, and is unique on a given host machine. For anonymous volumes, the first field is omitted.
• The second field is the path where the file or directory are mounted in the container.
• The third field is optional, and is a comma-separated list of options, such as ro.

See https://docs.docker.com for more information on specifying volume mappings in Docker.

Recommended volume mappings are:

• Nginx logs: $PORTAL_ROOT/logs/nginx:/var/log/nginx
• PHP logs: $PORTAL_ROOT/logs/php:/var/simian_portal/log:
• Application configurations: $PORTAL_ROOT/userconfig/persistent/config/configurations:/var/simian_portal/config/configurations
• Users and groups configurations (managed mode): $PORTAL_ROOT/userconfig/persistent/config/users:/var/simian_portal/config/users
• Front-end versions: $PORTAL_ROOT/userconfig/persistent/apps:/var/simian_portal/public/apps
• PHP sessions: $PORTAL_ROOT/userconfig/persistent/userSessionsData:/var/simian_portal/userSessionsData

Volume mappings can also be used to provide certificates for SSL.

• path/to/my/certs/certs.crt:/etc/nginx/ssl/simian_suite_portal.crt
• path/to/my/certs/key.key:/etc/nginx/ssl/simian_suite_portal.key
• path/to/my/certs/cacert.pem:/etc/ssl/certs/cacert.pem

Advanced

If the settings provided in this chapter are not sufficient, it is possible to provide custom configuration files. These files need to be mounted in the correct locations.