On-Premise Installation

Introduction

This installation guide is targeting system administrators who want to install Cawemo Enterprise On-Premise 1.7 on their own IT infrastructure or private cloud. This version of Cawemo is exclusively available for Camunda Enterprise customers and requires a separately sold license.

Prerequisites

Cawemo consists of several components that are tied together with Docker Compose. In addition to those components that ship with Cawemo, a few external systems are required for running it, which need to be set up separately.

• Server with Linux operating system on amd64 architecture
• Docker CE 17.03 or newer
• Docker Compose 1.23.0 or newer
• PostgreSQL 9.6 (newer versions may work as well)
  • Postgres is used as persistent storage for all Cawemo data (e.g. BPMN workflows, comments etc.) as well as Camunda Account data
  • Please set up two separate databases for Cawemo and Camunda Account
  • Note: Cawemo’s database user needs to be granted the superuser privilege

1. Log-in to Camunda Docker Registry

The Cawemo Docker images are hosted on our dedicated Docker registry and are available to enterprise customers only. You can browse the available images in our Docker registry after logging in with your credentials.

Make sure to log in correctly:

$ docker login registry.camunda.cloud
Username: your_username
Password: ******
Login Succeeded

2. Download docker-compose.yml File

Download this docker-compose.yml file to your server directory.

3. Create an .env File

In the same server directory, create an .env file with the following content and adjust the values according to your own setup, especially the path to the license file.

docker run --rm -t \
  registry.camunda.cloud/iam-ee/iam-utility:v1.1.6 \
  yarn run generate-jwk

##########
# CAWEMO #
##########
# Please use the domain root for Cawemo's SERVER_URL
SERVER_URL=https://cawemo.example.com
SERVER_HOST=cawemo.example.com
SERVER_HTTPS_ONLY=true
SERVER_SESSION_COOKIE_SECRET=

############
# DATABASE #
############
DB_HOST=postgresql.example.com
DB_PORT=5432
DB_NAME=cawemo
DB_USER=cawemo
DB_PASSWORD=top-secret-123

#########
# EMAIL #
#########
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_USER=cawemo
SMTP_PASSWORD=top-secret-123
SMTP_ENABLE_TLS=true
SMTP_FROM_ADDRESS=cawemo@example.com
SMTP_FROM_NAME=Cawemo

##############
# WEBSOCKETS #
##############
BROWSER_WEBSOCKET_HOST=ws.example.com
BROWSER_WEBSOCKET_PORT=8060
BROWSER_WEBSOCKET_FORCETLS=true
WEBSOCKET_SECRET=

################################
# FRONTEND STYLE CUSTOMIZATION #
################################
THEME_COLOR_PRIMARY=#2875cc
THEME_COLOR_SECONDARY=#00bfa5
THEME_COLOR_ACCENT=#343434
# A PNG file of 134px width and 20px height is recommended
THEME_LOGO_URL=/img/cawemo-enterprise-default.min.svg

###########
# LICENSE #
###########
HOST_LICENSE_FILE_PATH=/path/to/license.txt

###################
# Camunda Account #
###################
# The URL at which users will access Camunda Account
# Please note: this needs to be different than Cawemo's SERVER_URL
IAM_BASE_URL=
# A secret of at least 32 characters used by Cawemo to authenticate to
# Camunda Account
CLIENT_SECRET=
# A secret of 32 characters to encrypt client secrets in the
# Camunda Account database
IAM_DATABASE_ENCRYPTION_KEY=
# A 4096 bits RSA private key in JSON Web Key (JWK) format.
# It will be used to sign the access tokens issues by Camunda Account.
IAM_TOKEN_SIGNING_KEY=
# How to connect Camunda Account to a PostgreSQL database
IAM_DB_HOST=
IAM_DB_PORT=
IAM_DB_PASSWORD=
IAM_DB_USER=
IAM_DB_NAME=

########
# LDAP #
########
# Set to true to use users from LDAP
LDAP_ENABLED=false
# The URL at which the LDAP server is reachable
IAM_LDAP_SERVER_URL=
# Optional: The domain of an Active Directory (AD) LDAP server
# Only to be set if AD is used
IAM_LDAP_DOMAIN=
# The credentials for binding the Camunda Account service to the
# LDAP server. Must be empty if connecting to an AD server.
IAM_LDAP_MANAGER_DN=
IAM_LDAP_MANAGER_PASSWORD=
# The start location for LDAP search
# Optional if AD is used - determined from configured domain if empty
IAM_LDAP_BASE_DN=
# Optional: The start location for user search.
# Relative to IAM_LDAP_BASE_DN. Must be empty if AD is used.
IAM_LDAP_USER_SEARCH_BASE=
# Optional: A filter to restrict the group of users to search in
IAM_LDAP_USER_SEARCH_FILTER=

# The attribute names used on the LDAP server.
# IAM_LDAP_UUID_ATTRIBUTE must be set to an attribute holding a
# universally unique identifier (UUID) of a user.
# Standard LDAP servers typically support the `EntryUUID` attribute.
# Active directory provides `ObjectGUID` and other attributes with UUIDs.
IAM_LDAP_UUID_ATTRIBUTE=

# IAM_LDAP_USER_NAME_ATTRIBUTES is used to extract the full name of
# the user, can be composed of multiple attribute names separated
# by a comma.
IAM_LDAP_USER_NAME_ATTRIBUTES=

# IAM_LDAP_USER_EMAIL_ATTRIBUTE is used to determine a user's email
# address that is also used for log in
IAM_LDAP_USER_EMAIL_ATTRIBUTE=

For more details on how to configure the LDAP integration of Camunda Account, please refer to LDAP Support.

4. Configure Your Network

To let users access Cawemo via their web browsers there are a couple of requirements that the system administrator has to fulfill usually using some kind of reverse proxy server.

• The SERVER_URL and IAM_BASE_URL specified in the .env file must be accessible by the user’s web browser via HTTPS with certificate validation.
  • The configuration above enforces the use of HTTPS. You can change this by setting SERVER_HTTPS_ONLY=false, but we do not recommend doing this in a production environment.
• The traffic for Cawemo has to be proxied to port 8080 on the host running the Docker containers.
• The traffic for Camunda Account has to be proxied to port 8090 on the host running the Docker containers.
• The domain configured for Camunda Account must have a DNS resolution configured to be accessible to the web browser and the Cawemo backend (Docker container).
• In addition to that the reverse proxy must support websockets and allow the user’s web browser to connect to the BROWSER_WEBSOCKET_HOST and BROWSER_WEBSOCKET_PORT depending on the setting of BROWSER_WEBSOCKET_FORCETLS with TLS and certificate validation enabled. This traffic has to be proxied to port 8060 on the host running the Cawemo Docker containers.

Please also ensure that Cawemo and Camunda Account can correctly access other services like the PostgreSQL database and the SMTP server.

For an example on how to configure Cawemo using a reverse proxy server with SSL support please refer to Reverse Proxy Configuration.

5. Run Cawemo

You should now be able to start up Cawemo by issuing:

docker-compose up -d

Point your web browser to the URL you defined above as SERVER_URL to verify that the application is running.

6. Configure Admin User

When LDAP Is Disabled

For the initial setup of Cawemo and to add more users, you need to create an admin user. When you open Cawemo for the first time, you will see an Admin Setup page. Please enter your e-mail address there and continue with the sign-up.

Once the admin user has been created, you will be able to invite more users to Cawemo. To do so, please open the Settings page from the user menu and click on Manage members.

Make sure that your SMTP server is up and running so that the users will receive invitations via email.

When LDAP Is Enabled

The first user that logs into Cawemo with their LDAP credentials acts as admin user. Subsequent users that log in are added as collaborators of the admin’s organization.