CMDBuild READY2USE on AWS User Guide

Overview

This image runs CMDBuild READY2USE, the open source Configuration Management Database (CMDB) and IT asset and service management platform from Tecnoteca. CMDBuild lets IT and facilities teams model configuration items and their relationships, track hardware and software inventory, run IT service management and workflow processes, build reports and dashboards, and integrate with other systems through a REST API. The READY2USE edition ships a complete, ready to use data model, so a full asset and service management platform is running within minutes of launch.

CMDBuild runs as a Java web application on Apache Tomcat 10 with the OpenJDK 17 JRE, bound to loopback 127.0.0.1:8080, behind nginx acting as a reverse proxy on port 80. A PostgreSQL 17 database with the PostGIS extension, listening on loopback only and stored on a dedicated data volume, holds every configuration item, relationship, process and report. Systemd manages the Tomcat service, PostgreSQL and nginx, starting them on boot and restarting them on failure. The application is served under the /cmdbuild context path with its web interface at /cmdbuild/ui/, so the bare root redirects there.

CMDBuild secures its web interface with its own administrator login. On the first boot of every deployed instance a one shot service generates a fresh PostgreSQL role password and a fresh administrator password, both unique to that instance, and rotates the shipped default admin login so it no longer works, all before the public web interface is started. Two instances launched from the same Amazon Machine Image therefore never share credentials, and the well known default admin/admin login never works on a deployed instance. The administrator password is written to /root/cmdbuild-credentials.txt with mode 0600 so that only the root user can read it.

This image ships the GNU AGPL-3.0 open source CMDBuild READY2USE distribution unmodified. READY2USE is Tecnoteca's free, full featured ready to use data model on top of the open source CMDBuild core; it is not a limited edition.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the CMDBuild web interface
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for CMDBuild. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. CMDBuild is a Java and Tomcat application that runs alongside PostgreSQL, so 8 GiB of memory is a sensible minimum. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the web interface. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a minute or two after the instance state becomes Running and the status checks pass, while the per instance database and administrator passwords are generated, the default login is rotated and the application starts.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg CMDBuild Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=cmdbuild}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Step 4: Retrieve Your Administrator Password

On the first boot CMDBuild generated an administrator password unique to this instance and wrote it, together with the database credentials, to a root only file. Read it with sudo:

sudo cat /root/cmdbuild-credentials.txt

The file lists the sign in URL, the administrator login and password, and the PostgreSQL database name, user and password:

cmdbuild.url=http://<instance-public-ip>/cmdbuild/ui/
cmdbuild.admin.login=admin
cmdbuild.admin.pass=<generated-password>
cmdbuild.db.name=cmdbuild
cmdbuild.db.user=cmdbuild
cmdbuild.db.pass=<generated-password>

The administrator login is admin, but the password is the generated value from this file, not the upstream default. The shipped admin/admin login is rotated on first boot and does not work.

Step 5: Sign In to CMDBuild

Browse to http://<instance-public-ip>/ in your web browser. The bare root redirects to the CMDBuild sign in page under the /cmdbuild/ui/ path. Sign in with the login admin and the password from /root/cmdbuild-credentials.txt.

After signing in you land on the service desk dashboard, with the Tickets Summary and navigation to the Registry, Asset Inventory and Service desk down the left.

As a first step, change the administrator password to one of your own choosing from the user menu, and create additional user accounts so each team member signs in with their own login.

Step 6: Explore the Asset Inventory

The READY2USE data model gives you a ready made configuration management database. Expand Asset Inventory in the left navigation and open a configuration item class, such as Computer, to see its cards. Each class has its own attributes, columns and lifecycle state.

Use the Add card button to create a configuration item, then open any card to record its attributes, relationships, history and attachments. CMDBuild can also generate a QR code for a card so you can label and track a physical asset.

Step 7: Model Relationships, Processes and Reports

With your configuration items in place you can build out the rest of the CMDB:

• Relationships - link configuration items to each other (for example a server to the applications it hosts, or an asset to its assigned employee and location) to build the relationship graph that a CMDB exists to capture.
• Service desk and processes - the READY2USE model includes IT service management workflows such as incident, request, change and problem management under the Service desk menu. Start a process from its class and follow it through its workflow steps.
• Dashboards and reports - open the dashboards and PDF reports included in the model to follow inventory, coverage and service performance.

Step 8: Use the REST API

CMDBuild exposes a REST API on the same port 80, under the /cmdbuild/services/rest/v3/ path, for integration with other tools. Authenticate by creating a session with the administrator credentials (or a dedicated API user) and the service scope, which returns a session token you then send in the CMDBuild-Authorization header:

TOKEN=$(curl -s -H 'Content-Type: application/json' \
  --data '{"username":"admin","password":"<your-password>","scope":"service"}' \
  'http://<public-ip>/cmdbuild/services/rest/v3/sessions?returnId=true' \
  | sed -n 's/.*"_id":"\([^"]*\)".*/\1/p')

curl -s -H "CMDBuild-Authorization: $TOKEN" \
  http://<public-ip>/cmdbuild/services/rest/v3/classes

Create a dedicated API user for automated access rather than using the administrator account.

Architecture and Security

The image is secure by default:

• CMDBuild binds to loopback only. nginx on port 80 is the sole public listener and reverse proxies to the application:

ss -tln | grep -E ':80|:8080|:5432'

LISTEN  127.0.0.1:5432          (PostgreSQL, loopback only)
LISTEN  0.0.0.0:80              (nginx reverse proxy)
LISTEN  127.0.0.1:8080          (Tomcat / CMDBuild, loopback only)

• Authentication is enforced. The REST session endpoint returns 401 for an unknown credential, and the bare root returns a 302 redirect into the /cmdbuild/ui/ interface.
• The shipped default admin/admin login is rotated on first boot and does not work. Only the generated per instance password authenticates.
• The administrator password is stored in /root/cmdbuild-credentials.txt with mode 0600, readable only by root.

You can confirm the service state and health on the instance:

systemctl is-active cmdbuild-tomcat.service postgresql.service nginx.service

curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1/cmdbuild/ui/

Step 9: Enable HTTPS with a Custom Domain

For production use, place your instance behind a domain name and enable TLS. Point a DNS A record at the instance's public IP, then either terminate TLS at an AWS Application Load Balancer in front of the instance, or install a certificate directly on the instance with Certbot and the nginx plugin:

sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

Certbot obtains a certificate and updates the nginx site to serve CMDBuild over HTTPS on port 443, with automatic renewal.

Backup and Maintenance

• Database - the application data lives in the PostgreSQL cmdbuild database. Back it up with pg_dump:

sudo -u postgres pg_dump cmdbuild | gzip > cmdbuild-$(date +%F).sql.gz

• Configuration - the Tomcat and CMDBuild configuration lives under /opt/cmdbuild-tomcat/conf, including conf/cmdbuild/database.conf. Include it in your backups.
• Snapshots - take periodic EBS snapshots of the root and data volumes for point in time recovery.
• Updates - apply operating system security updates with sudo apt-get update && sudo apt-get upgrade. For CMDBuild version upgrades, contact cloudimg support for a guided procedure that preserves your database.

Support

cloudimg provides 24/7 technical support for this image by email and live chat at support@cloudimg.co.uk. Our engineers help with deployment, data model configuration, the REST API, workflow and process setup, user management, database tuning, TLS and scaling. Critical issues receive a one hour average response.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.