It is not always necessary to manually install the UM with the described installation method. In some cases it makes sense to run the UM in a docker container:
If you have a dockerized application infrastructure
To develop CSE based applications in a local UM instance
This section describes how you can create a customized UM Docker image.
We do not provide pre-built docker images because
years of practice have shown that setting up a UM instance usually involves customizing it in many ways and touching and adding a lot of files. That means, you would have to ADD or COPY a lot of files anyway.
While configuration variables (“cmsbs.properties”) can be passed via environment variables, there are a number of situations where whole files need to be added to the image: i.e. the licence file, sender and reply-to addresses, additions or modifications to the data model, optional UM Apps or custom CSE code.
Often times there will be more than just one single UM instance, so there is the need to end up with three or sometimes even more slightly different setups and thus different images.
The more customizing needs to be done, the more it makes sense to be able to first implement and test these customizations on your local machine and let the docker image create when you are done.
There is a tool that is desiged to do exactly that: The UM Kickstarter.
Creating a customized docker image
To create your own custom UM docker image, install UM Kickstarter following Install Kickstarter, first.
Next, create a new project:
umkickstarter my-um-project cd my-um-project
Next, copy your personal license file to env/devel/cmsbs-conf/cmsbs.license.
You are now ready to create your custom UM docker image:
gradle dockerimage -Penv=devel
Running a UM from a custom docker image
Start your dockerized UM:
docker run --rm --network host \
-e UM_ADMIN_USERNAME=admin -e UM_ADMIN_PASSWORD=admin \
myproject:devel
Go to http://localhost:8080/cmsbs and login as admin / admin.
The default for Kickstarter based UM installations is to use an embedded H2 database that stores its data in /UM/cmsbs-work/db.h2.* inside the docker container’s volume. As this is fine for local development you probably want to use a ‘real’ database engine at some point in time.
Running a local ‘real’ database
There is quite a number of supported database engines to choose from (see Installation Requirements for a list of officially supported databases).
Select one of the database engines listed below and start an instance with the given docker run command.
Configure UM to use new database
Create a file env/devel/cmsbs-conf/conf.d/database.properties below your Kickstarter directory and paste the given UM configuration snippet according to the database chosen.
Create the directory cmsbs/WEB-INF/lib/ below your Kickstarter directory and add the following line to your build.gradle file:
pinuts.extraDist = [ 'cmsbs/WEB-INF/lib' ]
Download the appropriate JDBC driver and copy the JAR file to the directory cmsbs/WEB-INF/lib/ your just created.
Recreate and run docker image using the freshly created database:
gradle dockerimage -Penv=devel
docker run --rm --network host \
-e 'UM_ADMIN_USERNAME=admin' -e 'UM_ADMIN_PASSWORD=admin' \
myproject:devel
The UM instance running on http://localhost:8080/cmsbs should now populate and use the new database.
Docker images for popular database engines
The following represents a subset of the supported databases for which there are easy to use docker images available on docker hub.
Each subsection contains a docker run command to start the according database listening on its respective standard TCP port and a docker run command to start a UM instance using that very database.
Postgres 12.3
Run Postgres on localhost:5432:
docker run \
-e POSTGRES_PASSWORD=mysecretpassword \
-p 5432:5432 \
--name postgres \
postgres:12.3
UM configuration:
cmsbs.database.url = "jdbc:postgresql://localhost:5432/" cmsbs.database.user = "postgres" cmsbs.database.password = "mysecretpassword"
Alternatively, inject database settings via environment variables:
docker run --rm --network host \
-e 'UM_ADMIN_USERNAME=admin' -e 'UM_ADMIN_PASSWORD=admin' \
-e 'cmsbs.database.url=jdbc:postgresql://localhost:5432/' \
-e 'cmsbs.database.user=postgres' \
-e 'cmsbs.database.password=mysecretpassword' \
myproject:devel
JDBC Driver: https://jdbc.postgresql.org/download
MySQL 8.0
Run MySQL on localhost:3306:
docker run \
-e MYSQL_DATABASE=um -e MYSQL_ROOT_PASSWORD=secret \
-p 3306:3306 \
--name mysql \
mysql:8.0 \
--max-allowed-packet=256m
UM configuration:
cmsbs.database.url = "jdbc:mysql://localhost:3306/um?allowPublicKeyRetrieval=true" cmsbs.database.user = "root" cmsbs.database.password = "secret" cmsbs.database.mysql.Unicode = true
Alternatively, inject database settings via environment variables:
docker run --rm --network host \
-e 'UM_ADMIN_USERNAME=admin' -e 'UM_ADMIN_PASSWORD=admin' \
-e 'cmsbs.database.url=jdbc:mysql://localhost:3306/um?allowPublicKeyRetrieval=true' \
-e 'cmsbs.database.user=root' \
-e 'cmsbs.database.password=secret' \
myproject:devel
JDBC Driver: https://dev.mysql.com/downloads/connector/j/
MariaDB 10
Run MariaDB on localhost:3306:
docker run \
-e MYSQL_DATABASE=um -e MYSQL_USER=um -e MYSQL_PASSWORD=secret \
-e MARIADB_RANDOM_ROOT_PASSWORD=true \
-p 3306:3306 \
--name mariadb \
mariadb:10 \
--max-allowed-packet=256m
UM configuration:
cmsbs.database.url = "jdbc:mysql://localhost:3306/um?allowPublicKeyRetrieval=true" cmsbs.database.user = "um" cmsbs.database.password = "secret" cmsbs.database.mysql.Unicode = true
Alternatively, inject database settings via environment variables:
docker run --rm --network host \
-e 'UM_ADMIN_USERNAME=admin' -e 'UM_ADMIN_PASSWORD=admin' \
-e 'cmsbs.database.url=jdbc:mysql://localhost:3306/um?allowPublicKeyRetrieval=true' \
-e 'cmsbs.database.user=um' \
-e 'cmsbs.database.password=secret' \
myproject:devel
JDBC Driver: https://dev.mysql.com/downloads/connector/j/
MSSQL 2022
Run MSSQL on localhost:1433:
docker run \
-e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=S3cre7pw' -e 'MSSQL_PID=Express' \
-p 1433:1433 \
--name mssql2017 \
mcr.microsoft.com/mssql/server:2022-latest
UM configuration:
cmsbs.database.url = "jdbc:sqlserver://localhost:1433;trustServerCertificate=true" cmsbs.database.user = "sa" cmsbs.database.password = "S3cre7pw" cmsbs.database.mssql.Unicode = true
Alternatively, inject database settings via environment variables:
docker run --rm --network host \
-e 'UM_ADMIN_USERNAME=admin' -e 'UM_ADMIN_PASSWORD=admin' \
-e 'cmsbs.database.url=jdbc:sqlserver://localhost:1433;trustServerCertificate=true' \
-e 'cmsbs.database.user=sa' \
-e 'cmsbs.database.password=S3cre7pw' \
myproject:devel
JDBC Driver: https://docs.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-ver15
Oracle 11g
Run Oracle on localhost:1521:
docker run \
-p 1521:1521 \
--name oracle-xe-11g \
oracleinanutshell/oracle-xe-11g:latest
UM configuration:
cmsbs.database.url = "jdbc:oracle:thin:@localhost:1521:xe" cmsbs.database.user = "system" cmsbs.database.password = "oracle"
Alternatively, inject database settings via environment variables:
docker run --rm --network host \
-e 'UM_ADMIN_USERNAME=admin' -e 'UM_ADMIN_PASSWORD=admin' \
-e 'cmsbs.database.url=jdbc:oracle:thin:@localhost:1521:xe' \
-e 'cmsbs.database.user=system' \
-e 'cmsbs.database.password=oracle' \
myproject:devel
JDBC Driver: https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html (Oracle account required!)
DB2 11
Run DB2 on localhost:50000:
docker run \
-e LICENSE=accept -e DB2INST1_PASSWORD=secret -e DBNAME=um \
-p 50000:50000 \
--privileged --ipc=host \
--name db2 \
ibmcom/db2:11.5.7.0
UM configuration:
cmsbs.database.url = "jdbc:db2://localhost:50000/um" cmsbs.database.user = "db2inst1" cmsbs.database.password = "secret"