Getting Started

• 1: System Requirements
• 2: Installation
• 3: Update
• 4: Setup Environment
• 5: HTTPS
• 6: Login

1 - System Requirements

Processor

• x86-64 compatible server CPU
• 8-cores or more
• Example: Intel Xeon E5 or later/equivalent AMD Epyc

Memory (RAM)

• Minimum 16 GB
• 32 GB or more recommended

Storage

• SSD with at least 10 GB free storage space for application, database, and container
• Or more, depending on the data volume

Operating System

Recommended OS: Ubuntu 20.04 LTS and Ubuntu 24.04 LTS

We do not support Windows at this moment. If you still want to run it on Windows, here’s a guide.

Software requirements

Common Linux Utils

• curl, tar, nano (or alternatives)

Docker

• Docker Engine v27.2.0+ with docker-compose-plugin v2.29.7+
• Example:

➜  docker --version
Docker version 27.3.1, build ce12230
➜  docker compose version
Docker Compose version v2.29.7

You may also try alternatives such as Podman, we do not support it at the moment.

Network requirements

• Stable network connection with sufficient bandwidth for data transfer between server and clients. 1+ gbps recommended

Security requirements

User privileges

• Make sure that the server has the appropriate user rights for managing Docker containers.

Firewall

• Configure the firewall to allow the traffic required to access the application.
  • Incoming Port 443 (or custom) for HTTPS (For IQ-Software, CDM-Server Webapp).
  • Outgoing Port 636 (or custom) for LDAPS
  • Outgoing Port 443 for HTTPS for Azure, OCI Image Pulls, etc.

2 - Installation

Step 1: Install Docker Compose

Make sure Docker Engine (with docker-compose-plugin) is installed on your system. See System Requirements for more details.

Step 2: Download the Docker-Compose File

curl -s https://get.apis.de/cdm.sh | bash

curl -s https://get.apis.de/cdm.sh | bash -s v1.0.0

#!/bin/bash

# URL of the tar.gz file
url="https://get.apis.de/cdm/latest.tar.gz"

# Download the tar.gz file
curl -O "$url"

# Extract the tar.gz file
tar -xzvf "latest.tar.gz"

# Optional: Remove the tar.gz file after extraction
rm "latest.tar.gz"

chmod +x download
chmod +x start
chmod +x stop

echo "CDM setup has been downloaded and extracted."

Step 3: Create the DotEnv Files

To use the server, you need to provide some data in the form of two DotEnv files:

• .env
• .env.idp

Create new DotEnv files, copy the contents of the example files, and update the values with your own configuration.

.env File

Example: .env.example

cp .env.example .env && nano .env

.env.idp File

Example: IdP (ID Provider) specific DotEnv files:

• .env.idp.azure.example
• .env.idp.ldaps.example
• .env.idp.local.example

• Select Identity Provider
• Local
• Azure
• LDAPS

cp .env.idp.local.example .env.idp && nano .env.idp

cp .env.idp.azure.example .env.idp && nano .env.idp

cp .env.idp.ldaps.example .env.idp && nano .env.idp

Step 4: Login and Download CDM-Server Images

Use the following command to login and download the CDM-Server images. You’ll be asked to enter username and password.

sudo ./download

Step 5. Start the CDM-Server Services

sudo ./start

sudo ./stop

Step 6. Access CDM-Server

Please see Login for more information.

3 - Update

If you want to update your CDM-Server instance to a new version, the steps are quite simple:

Step 1: Take a Backup

Please see this page for backup instructions.

Step 2: Update

You need to download the new version and (re)start the server.

This is essentially, step 4 and 5 of installation process.

4 - Setup Environment

Please set some basic details of the server in the .env file. You can find the .env.example file in the root directory of the project.

Configuration

cp .env.example .env && nano .env

## HELP
# https://get.apis.de/docs/server/env/

## ABOUT
# This will be used to create the root business unit
# Do not use special characters
COMPANY_NAME=

## CDM HOST and PORT
# The hostname to access the server.
# Must not contain protocol such as https://
# Must not have port number
# Must not have trailing slash
# Example: cdm.example.com
CDM_HOST=localhost

# Just the port number; 443 recommended
# Default port is 443
CDM_PORT=443

## USE CUSTOM HTTPS CERTIFICATE FOR CDM-SERVER (PRIVATE-KEY)
# If you have a custom certificate (private-key), set this to true.
# You need to place the custom certificate in the same directory as your `docker-compose.yml` file (where you have downloaded CDM-Server).
# The certificate file name must be `cdm-server.pfx`
# For a false value, a self-signed certificate will be created and used for HTTPS.
# Please check [help docs for more information](https://get.apis.de/docs/server/https/).
# Default is false
USE_CUSTOM_CERT=false

### CUSTOM CERTIFICATE PASSWORD
# If you are using a custom certificate (`USE_CUSTOM_CERT=true`) and your certificate is password-protected, set the password here.
# Otherwise, leave it empty.
CUSTOM_CERT_PASS=

Example

COMPANY_NAME=APIS Informationtechnologien GmbH
CDM_HOST=cdm.apis.de
CDM_PORT=443
USE_CUSTOM_CERT=true
CUSTOM_CERT_PASS=supersecretpassword

COMPANY_NAME

This is the name of your company. It will be used to create the root business unit.

USE_CUSTOM_CERT

See HTTPS for more information.

Setup Up ID Provider (IdP)

After you are done setting up .env, please head over to the IdP Docs to setup .env.idp file.

Permissions for the DotEnv Files

It is recommended that you do not allow other users in same server system to read the DotEnv files as some of them can contain credentials. You can try chmod 600 on all of them.

5 - HTTPS

CDM-Server takes the secure-by-design approach and thus enforces HTTPS.

HTTPS to Access CDM-Server

If you set the USE_CUSTOM_CERT environment variable to true:

• You can provide your own certificate. The server will use these files to serve HTTPS.
• This can be self-signed or CA-signed (recommended).
• There is a dummy file ./cdm-server.pfx where you have downloaded the CDM-Server. Just replace it with your own certificate.

Renew Certificate

Once you have the renewed certificate file

• Stop the server
• Replace the file
• Restart the server

This will apply the new certificate.

Self-Signed Certificate

If the variable is set to false, the server will generate and use a self-signed certificate. You can find it in

• ./.data/certs/<CDM_HOST>.cert.p7b - X.509 certificate (contains the public key) that you can import to your browser.
• ./.data/certs/<CDM_HOST>.pfx - Certificate in PKCS#12 format. It contains private Key that you should not share.

Install Self-Signed Certificate on User’s Machine

Please see Install Self-Signed Certificate for more information.

LDAP over SSL

For this, look into LDAP documentation.

6 - Login

1. Open your browser and navigate to the CDM-Server URL. The module select page will appear.
2. Click Dashboard
3. In case of Local or Ldaps, enter your username and password
4. In case of Azure, you will be redirected to Azure login page.