Configuration

This guide covers configuring DBCalm after installation.

Database Credentials

Location

/etc/dbcalm/credentials.cnf

Format

The credentials file uses MySQL configuration file format:

[client-dbcalm]
user=backupuser
password=your_secure_password
host=localhost

Warning

The package creates this file with a placeholder password (changeme). You MUST update it with your actual MariaDB backup user password.

Updating Credentials

sudo nano /etc/dbcalm/credentials.cnf

After updating, restart the API:

sudo systemctl restart dbcalm-api

SSL Certificates

Development (Self-Signed - Included)

The package automatically generates a self-signed SSL certificate:

  • Certificate: /etc/dbcalm/ssl/fullchain-cert.pem

  • Private Key: /etc/dbcalm/ssl/private-key.pem

Valid for dbcalm.localhost. This is safe for development and testing but will show browser warnings when accessing the API. To proceed, click “Advanced” (or similar) and then “Proceed to localhost” (or “Accept the Risk”) in your browser.

Trusted Development Certificates

For development environments where you want to avoid browser warnings, you can use mkcert to generate locally-trusted certificates. See the mkcert documentation for installation and usage instructions.

After generating your certificates with mkcert, place them in:

  • /etc/dbcalm/ssl/fullchain-cert.pem

  • /etc/dbcalm/ssl/private-key.pem

Then restart the API:

sudo systemctl restart dbcalm-api

Production SSL Certificates

For production deployments, use Let’s Encrypt to obtain free, trusted SSL certificates for your domain. See the Let’s Encrypt documentation for detailed instructions.

After obtaining your certificates, place them in:

  • /etc/dbcalm/ssl/fullchain-cert.pem (your certificate + chain)

  • /etc/dbcalm/ssl/private-key.pem (your private key)

Then restart the API:

sudo systemctl restart dbcalm-api

API Configuration

Configuration File

Location: /etc/dbcalm/config.yml

The package creates a template with auto-generated JWT secret key.

Available Options

# CORS - Allowed origins for web frontend
cors_origins:
  - "https://yourdomain.com"
  - "https://admin.yourdomain.com"

# API binding
api_host: "0.0.0.0"  # Listen on all interfaces
api_port: 8335

# SSL certificates
ssl_cert: "/etc/dbcalm/ssl/fullchain-cert.pem"
ssl_key: "/etc/dbcalm/ssl/private-key.pem"

# Logging
log_file: "/var/log/dbcalm/dbcalm.log"
log_level: "info"  # Options: debug, info, warning, error

# JWT authentication (auto-generated by package)
jwt_secret_key: "your-generated-secret-here"
jwt_algorithm: "HS256"

CORS Configuration

To allow your web frontend to access the API, add its domain to cors_origins:

cors_origins:
  - "https://dbcalm.yourdomain.com"
  - "https://admin.yourdomain.com"
  - "http://localhost:3000"  # For local development

Restricting API Access

To bind the API to a specific network interface:

api_host: "10.0.0.50"  # Internal network only

Applying Configuration Changes

After editing config.yml:

sudo systemctl restart dbcalm-api

Backup Storage

Backups are stored in: /var/lib/dbcalm/backups/

This directory is created automatically with proper permissions.

Security

Network Access

The API runs on port 8335 by default. This port must be accessible to any service or user that needs to call the API.

Warning

Access should be restricted and not exposed to the entire internet. Limit access to specific IP addresses, such as your own IP or your organization’s network range, using your firewall configuration.

File Permissions

Verify critical file permissions:

# Credentials - should be mysql:dbcalm with mode 640
ls -l /etc/dbcalm/credentials.cnf

# SSL certificates - should be dbcalm:dbcalm with mode 640
ls -l /etc/dbcalm/ssl/*

# Configuration - should be dbcalm:dbcalm with mode 640
ls -l /etc/dbcalm/config.yml

# Database - should be mysql:dbcalm with mode 664
ls -l /var/lib/dbcalm/db.sqlite3

If permissions are incorrect:

sudo chown mysql:dbcalm /etc/dbcalm/credentials.cnf
sudo chmod 640 /etc/dbcalm/credentials.cnf

sudo chown dbcalm:dbcalm /etc/dbcalm/ssl/*
sudo chmod 640 /etc/dbcalm/ssl/*

sudo chown dbcalm:dbcalm /etc/dbcalm/config.yml
sudo chmod 640 /etc/dbcalm/config.yml

Troubleshooting

Service Won’t Start

Check service status:

sudo systemctl status dbcalm-api
sudo systemctl status dbcalm-cmd
sudo systemctl status dbcalm-mariadb-cmd

View detailed logs:

sudo journalctl -u dbcalm-api -n 100 --no-pager
sudo tail -n 100 /var/log/dbcalm/dbcalm.log

Database Connection Errors

Test credentials manually:

mysql --defaults-file=/etc/dbcalm/credentials.cnf -e "SHOW DATABASES;"

Verify backup user permissions:

SHOW GRANTS FOR 'backupuser'@'localhost';

Expected output should include:

GRANT RELOAD, PROCESS, REPLICATION CLIENT ON *.* TO 'backupuser'@'localhost'

SSL Certificate Errors

Verify certificate files exist and are readable:

sudo ls -l /etc/dbcalm/ssl/

Check certificate details:

sudo openssl x509 -in /etc/dbcalm/ssl/fullchain-cert.pem -text -noout | head -20

Permission Denied Errors

Check directory ownership:

ls -la /var/lib/dbcalm/
ls -la /var/log/dbcalm/
ls -la /etc/dbcalm/

Fix ownership if needed:

sudo chown -R mysql:dbcalm /var/lib/dbcalm/
sudo chown -R mysql:dbcalm /var/log/dbcalm/
sudo chown -R dbcalm:dbcalm /etc/dbcalm/

Command Services Not Running

DBCalm consists of three independent services:

  • dbcalm-api - The main API server

  • dbcalm-cmd - Command service for general operations

  • dbcalm-mariadb-cmd - Command service for MariaDB-specific operations

Check status of all services:

sudo systemctl status dbcalm-api dbcalm-cmd dbcalm-mariadb-cmd

Restart all services:

sudo systemctl restart dbcalm-api dbcalm-cmd dbcalm-mariadb-cmd

Or restart individually:

sudo systemctl restart dbcalm-api
sudo systemctl restart dbcalm-cmd
sudo systemctl restart dbcalm-mariadb-cmd

Port Already in Use

If port 8335 is already in use, you can change the API port.

Edit /etc/dbcalm/config.yml:

api_port: 8336  # Use different port

Then restart:

sudo systemctl restart dbcalm-api