On-Premise Installation

Introduction

This installation guide is targeting system administrators who want to install Cawemo Enterprise On-Premise 1.5 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.

Integration with Camunda Account

Camunda Account is our solution for Identity and Access Management (IAM). It enables single sign-on and central user management for Camunda products. Camunda Account is initially bundled with Cawemo, but it is a separate application. Cawemo and Camunda Account may be updated separately in the future when more Camunda products integrate Camunda Account.

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.

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.0.2 \
  yarn run generate-jwk

##########
# CAWEMO #
##########
SERVER_URL=https://cawemo.your-company.com
SERVER_HOST=cawemo.your-company.com
SERVER_HTTPS_ONLY=true
SERVER_SESSION_COOKIE_SECRET=

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

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

##############
# WEBSOCKETS #
##############
BROWSER_WEBSOCKET_HOST=cawemo.your-company.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
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=

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 which is not recommended for production use though.
• 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.

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

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.