Configuration
=============

This guide covers configuring DBCalm after installation.

Database Credentials
--------------------

Location
~~~~~~~~

``/etc/dbcalm/credentials.cnf``

Format
~~~~~~

The credentials file uses MySQL configuration file format:

.. code-block:: ini

   [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
~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   sudo nano /etc/dbcalm/credentials.cnf

After updating, restart the API:

.. code-block:: bash

   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 <https://github.com/FiloSottile/mkcert>`_ 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:

.. code-block:: bash

   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 <https://letsencrypt.org/getting-started/>`_ 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:

.. code-block:: bash

   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
~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   # 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``:

.. code-block:: yaml

   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:

.. code-block:: yaml

   api_host: "10.0.0.50"  # Internal network only

Applying Configuration Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After editing ``config.yml``:

.. code-block:: bash

   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:

.. code-block:: bash

   # 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:

.. code-block:: bash

   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:

.. code-block:: bash

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

View detailed logs:

.. code-block:: bash

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

Database Connection Errors
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Test credentials manually:

.. code-block:: bash

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

Verify backup user permissions:

.. code-block:: sql

   SHOW GRANTS FOR 'backupuser'@'localhost';

Expected output should include:

.. code-block:: text

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

SSL Certificate Errors
~~~~~~~~~~~~~~~~~~~~~~~

Verify certificate files exist and are readable:

.. code-block:: bash

   sudo ls -l /etc/dbcalm/ssl/

Check certificate details:

.. code-block:: bash

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

Permission Denied Errors
~~~~~~~~~~~~~~~~~~~~~~~~

Check directory ownership:

.. code-block:: bash

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

Fix ownership if needed:

.. code-block:: bash

   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:

.. code-block:: bash

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

Restart all services:

.. code-block:: bash

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

Or restart individually:

.. code-block:: bash

   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``:

.. code-block:: yaml

   api_port: 8336  # Use different port

Then restart:

.. code-block:: bash

   sudo systemctl restart dbcalm-api