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).

NameDescriptionDefault
SIMIAN_NGINX_SERVER_NAMENginx server namelocalhost
SIMIAN_NGINX_CLIENT_MAX_BODY_SIZEMaximum request body size256m
SIMIAN_NGINX_HTTPEnable HTTP0
SIMIAN_NGINX_HTTP_TO_HTTPSRedirect HTTP to HTTPS1
SIMIAN_NGINX_HTTPSEnable HTTPS1
SIMIAN_NGINX_KEEPALIVE_TIMEOUTTime-out of a request [s]2700

PHP

NameDescriptionDefault
SIMIAN_PHP_MEMORY_LIMITMaximum memory usage of the PHP process512M
SIMIAN_PHP_POST_MAX_SIZEMaximum request body size256M
SIMIAN_PHP_TIMEZONEPHP server time zoneEurope/Amsterdam
SIMIAN_PHP_UPLOAD_MAX_FILESIZEMaximum file upload size128M

Generic

NameDescriptionDefault
SIMIAN_PORTAL_EXTERNAL_URLExternal URL (add the port when not using defaults 80 or 443)https://localhost
SIMIAN_PORTAL_LOGOLogo to show on the login page etc.simian logo icon.svg
SIMIAN_PORTAL_FAVICONLogo to show on the tabssimian logo icon circle.svg
SIMIAN_PORTAL_NAVBAR_LOGOLogo to show in the portal navigation barsimian logo icon light.svg
SIMIAN_PORTAL_TITLETitle to show in the portal navigation barSimian Portal
SIMIAN_PORTAL_SUBTITLESubtitle to show in the portal navigation bar<undefined>
SIMIAN_ENABLE_CHECKMakes the check.php page public0

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.
NameDescriptionDefault
SIMIAN_PORTAL_AUTH_TYPEThe used authentication methodmanaged

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.

NameDescriptionDefault
SIMIAN_MAIL_FROM_ADDRESSThe from address for sending the invite<undefined>
SIMIAN_MAIL_FROM_NAMEThe from name for sending the inviteSimian Portal
SIMIAN_MAIL_SMTP_HOSTSMTP server address<undefined>
SIMIAN_MAIL_SMTP_PORTSMTP server port25
SIMIAN_RESET_ADMIN_PASSWORDMakes reset_admin_password.php public0

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 ve 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.

NameDescriptionDefault
SIMIAN_PORTAL_LDAP_AUTH_TIMEOUTAuthentication timeout1800
SIMIAN_PORTAL_LDAP_START_TLSStart TLS connectiontrue
SIMIAN_PORTAL_LDAP_HOSTHostname of the LDAP server<undefined>
SIMIAN_PORTAL_LDAP_PORTPort of the LDAP server389
SIMIAN_PORTAL_LDAP_USER_DOMAINYour microsoft domain name.<undefined>
SIMIAN_PORTAL_LDAP_BASE_DNTop level from where searches are being done in the LDAP server<undefined>
SIMIAN_PORTAL_LDAP_USERS_DNDistinguished name where searches will be exected for user<undefined>
SIMIAN_PORTAL_LDAP_USER_NAME_ATTRIBUTEUser attribute containing the name used for authenticationsAMAccountName
SIMIAN_PORTAL_LDAP_USER_PHOTO_ATTRIBUTEAttribute containing the user photothumbnailphoto
SIMIAN_PORTAL_LDAP_USER_DISPLAYNAME_ATTRIBUTEAttribute containing the user display namedisplayname
SIMIAN_PORTAL_LDAP_GROUP_NAME_ATTRIBUTEAttribute being searched for to identify user membershipsAMAccountName
SIMIAN_PORTAL_LDAP_READONLY_USERRead-only user 1<undefined>
SIMIAN_PORTAL_LDAP_READONLY_PASSWORDRead-only user password 1<undefined>
SIMIAN_PORTAL_LDAP_PORTAL_PARENT_GROUPSDirect subgroups are selectable in application configurations 2[]
SIMIAN_PORTAL_LDAP_PORTAL_ADMIN_GROUPSList of groups with admin portal access 2[]
1

The LDAP integration only uses user credentials for authentication. All other communication, e.g. for retrieval of user details and querying group membership, happens with a read-only LDAP user with username SIMIAN_PORTAL_LDAP_READONLY_USER and password SIMIAN_PORTAL_LDAP_READONLY_PASSWORD.

2

The value must be a list of strings, e.g: ['admin', 'consulting']. Leave unspecified to not restrict groups.

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.

NameDescriptionDefault
SIMIAN_PORTAL_AZURE_AD_TENANT_IDAzure Active Directory Tenant ID 3<undefined>
SIMIAN_PORTAL_AZURE_AD_CLIENT_IDClient application ID provided by Azure<undefined>
SIMIAN_PORTAL_AZURE_AD_CLIENT_SECRETClient Secret provided by Azure 4<undefined>
SIMIAN_PORTAL_AZURE_AD_CERT_THUMBPRINTThumbprint for certificate uploaded to Azure 5<undefined>
SIMIAN_PORTAL_AZURE_AD_PORTAL_ADMIN_GROUPSDirect subgroups are selectable in application configurations 6[]
SIMIAN_PORTAL_AZURE_AD_PORTAL_PARENT_GROUPSList of groups with user portal access 6[]
3

With Multitenant apps you can use "common" as Tenant ID, but using specific endpoint is recommended when possible.

4

Remember that this expires someday unless you have set it not to do so. When using private key and certificate for authentication, the client secret must not be set.

5

The private key corresponding to the certificate must be volume mapped to /var/simian_portal/config/certs/portal.key.

6

The value must be a list of strings, e.g: ['f2884a1c-62e8-425c-b32a-25881f375823', 'ea2d7058-a486-46c5-bc4b-7c7fc14db767']. Leave unspecified to not restrict groups.

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.

NameDescriptionDefaultMount volume
SIMIAN_CUSTOM_NGINX_CONFUse custom nginx.conf0/etc/nginx/nginx.conf
SIMIAN_CUSTOM_PHP_INIUse custom php.ini0/etc/php81/conf.d/custom.ini
SIMIAN_CUSTOM_CONFIG_PHPUse custom config.php0/var/simian_portal/config/config.php
SIMIAN_CUSTOM_MAIL_CONFIG_PHPUse custom mail_config.php0/var/simian_portal/config/mail_config.php