CMDB Operations & Services Runbook¶

This runbook outlines the standard operating procedures to start, stop, and check the status of the core Likpi CMDB components across both Linux and Windows environments.

Managing Services on Linux Environments¶

Managing the PostgreSQL Database¶

The database service is managed by the system administrator using the system service manager.

Check Status

$ sudo systemctl status postgresql

Start / Stop / Restart

$ sudo systemctl start postgresql
$ sudo systemctl stop postgresql
$ sudo systemctl restart postgresql

Managing the Frontend (Nginx)¶

The React frontend is served by Nginx]. Administrative privileges are required to manage this web server.

Check Status

$ sudo systemctl status nginx

Start / Stop / Restart

$ sudo systemctl start nginx
$ sudo systemctl stop nginx
$ sudo systemctl restart nginx

Managing the Backend (Java Vert.x)¶

For a production environment, it is highly recommended to manage the Java Vert.x backend as a systemd service. This allows it to run smoothly in the background under the likpiadm user.

Step 1: Create the systemd service file

With your system administrator, create a new service file]:

$ sudo vi /etc/systemd/system/cmdb-backend.service

Add the following configuration, ensuring the paths match your deployment:

[Unit]
Description=Likpi CMDB Backend Service
After=network.target postgresql.service

[Service]
Type=simple
User=likpiadm
Group=likpi
WorkingDirectory=/opt/likpi/cmdb-backend
ExecStart=/usr/bin/java -jar /opt/likpi/cmdb-backend/cmdb-app-1.0.0-SNAPSHOT-fat.jar -conf /opt/likpi/cmdb-backend/config.json
Restart=on-failure
RestartSec=10
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=cmdb-backend

[Install]
WantedBy=multi-user.target

Step 2: Enable and Manage the Service

Reload the systemd daemon to recognize the new service, and enable it to start on boot:

$ sudo systemctl daemon-reload
$ sudo systemctl enable cmdb-backend

Start / Stop / Status

$ sudo systemctl status cmdb-backend
$ sudo systemctl start cmdb-backend
$ sudo systemctl stop cmdb-backend

Managing Services on Windows Environments¶

If your CMDB solution is deployed on a Microsoft Windows Server, you can manage the frontend and backend services using the following procedures.

Managing the Frontend (Nginx on Windows)¶

If using Nginx for Windows, open a Command Prompt as Administrator and navigate to your Nginx installation directory (e.g., C:\nginx).

Start Nginx

C:\nginx> start nginx

Stop or Reload Nginx

C:\nginx> nginx -s quit
C:\nginx> nginx -s reload

Managing the Backend (Java Vert.x as a Windows Service)¶

To run the Java Vert.x fat JAR as a background Windows Service that restarts automatically on failure or system boot, it is recommended to use the open-source WinSW (Windows Service Wrapper) utility.

Step 1: Prepare the Service Wrapper

Download the latest WinSW executable (.exe) from its official GitHub releases page.
Rename the downloaded executable to cmdb-backend.exe and place it in your backend directory (e.g., C:\likpi\cmdb-backend\).

Step 2: Create the Service Configuration

In the same directory, create an XML file named exactly like the executable (cmdb-backend.xml) with the following configuration:

<service>
  <id>cmdb-backend</id>
  <name>Likpi CMDB Backend</name>
  <description>Runs the Java Vert.x Backend for Likpi CMDB</description>
  <executable>java</executable>
  <arguments>-jar C:\likpi\cmdb-backend\cmdb-app-1.0.0-SNAPSHOT-fat.jar -conf C:\likpi\cmdb-backend\config.json</arguments>
  <log mode="roll"></log>
  <onfailure action="restart" delay="10 sec"/>
</service>

Step 3: Install and Manage the Service

Open a Command Prompt as Administrator, navigate to the backend directory, and run the following commands to install and start the service]:

Install the service:

C:\likpi\cmdb-backend> cmdb-backend.exe install

Start the service:

C:\likpi\cmdb-backend> cmdb-backend.exe start

Check Status or Stop the service:

C:\likpi\cmdb-backend> cmdb-backend.exe status
C:\likpi\cmdb-backend> cmdb-backend.exe stop

Note

Once installed, the Likpi CMDB Backend service will also be visible and manageable directly from the native Windows Services application (services.msc).

Backup, Restore, and Log Rotation¶

Since the CMDB acts as the single source of truth for your infrastructure and GitOps audit trails, establishing a robust disaster recovery and log management strategy is critical.

Database Backup (PostgreSQL)¶

To create a manual, compressed backup of the cmdb database using the custom format (-F c), run:

$ sudo -u postgres pg_dump -F c -v -f /path/to/backup/cmdb_backup_$(date +%F).dump cmdb

For automated daily backups, it is highly recommended to set up a cron job. Open the postgres user crontab:

$ sudo -u postgres crontab -e

Add the following line to execute a backup every day at 2:00 AM:

0 2 * * * pg_dump -F c -f /path/to/backup/cmdb_backup_$(date +\%F).dump cmdb

Database Restore¶

In the event of a disaster recovery scenario, follow these steps to restore the database from a backup file.

Step 1: Stop the CMDB Backend Service To prevent active database connections or partial writes during the restore process, you must stop the application layer first.

$ sudo systemctl stop cmdb-backend

Step 2: Drop and Recreate the Database

$ sudo su - postgres
$ psql -c "DROP DATABASE cmdb;"
$ psql -c "CREATE DATABASE cmdb WITH ENCODING 'UTF-8';"
$ psql -c "GRANT ALL PRIVILEGES ON DATABASE cmdb TO cmdb_user;"
$ exit

Step 3: Restore the Data

$ sudo -u postgres pg_restore -d cmdb -v /path/to/backup/cmdb_backup_YYYY-MM-DD.dump

Step 4: Restart the Services

$ sudo systemctl start cmdb-backend

Backend Java Service Logging (logback.xml)¶

In addition to system-level service logs, the Java Vert.x backend natively manages its own application logs using Logback.

By default, the backend creates a dedicated logs directory within its working directory (e.g., /opt/likpi/cmdb-backend/logs/) and writes to a file named cmdb-application.log.

This native logging engine is self-managing and enforces the following internal rotation policies:

Daily Rotation: A new log file is automatically generated every day (e.g., cmdb-application.YYYY-MM-DD.log).
History Retention: The system retains a maximum of 30 days of historical log files.
Size Cap: The total size of the log directory is capped at 1GB; older files are deleted if this limit is exceeded.

If required, administrators can modify these limits by editing the logback.xml file included with the backend distribution.

Frontend Log Management and Rotation¶

To prevent application and web server logs from consuming all server disk space over time, log rotation must be enforced.

Linux Environments (logrotate) If your Java backend or Nginx server writes to standard log files in /var/log/, create a logrotate configuration:

$ sudo vi /etc/logrotate.d/cmdb-logs

Add the following policy to rotate logs daily, compress old logs, and keep a 14-day history:

/var/log/nginx/cmdb*.log /opt/likpi/cmdb-backend/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 likpiadm likpi
}

Note

If you are using syslog via systemd for the Java backend (as configured earlier in this runbook), systemd’s journald automatically handles log rotation. You can manage its limits by editing SystemMaxUse in /etc/systemd/journald.conf.

Windows Environments (WinSW) If you are running the backend as a Windows Service using WinSW, log rotation is natively handled by the <log mode="roll"></log> directive we previously configured in the cmdb-backend.xml file. This ensures logs are rolled over safely when they reach 10MB, retaining the last 8 files by default.