RadiatorDB Installation

RadiatorDB Installation

This guide covers the basic deployment of RadiatorDB with a single PostgreSQL instance.

Prerequisites

• A host for Radiator server
• A host for PostgreSQL (version 14 or later)(Can be same host for small installations)
• Network connectivity between the two hosts on TCP port 5432

Step 1: Install Radiator

Install Radiator on the first host following the Basic Installation guide. RadiatorDB is built into Radiator and requires no additional packages.

Step 2: Install and Configure PostgreSQL

On the database host, install PostgreSQL and create credentials for RadiatorDB.

sudo apt-get update

# Install PostgreSQL (Debian/Ubuntu example)
sudo apt-get install postgresql

# Switch to the postgres system user
sudo -u postgres psql

Inside the PostgreSQL shell, create a dedicated user:

CREATE USER radiatordb_admin WITH PASSWORD 'r4d1at0rDB!secret';
ALTER USER radiatordb_admin CREATEDB;

RadiatorDB automatically creates the database when Radiator starts. The CREATEDB privilege allows the user to create the database. As the database creator, the user automatically becomes its owner, which grants the privileges needed to manage SQL tables, indexes, and logical replication configurations.

Ensure PostgreSQL accepts connections from the Radiator host. Edit pg_hba.conf to allow the Radiator host IP (replace 192.168.1.10 with the actual Radiator host address):

host    radiatordb    radiatordb_admin    192.168.1.10/32    scram-sha-256

Edit postgresql.conf to listen on the network interface:

listen_addresses = '*'

Restart PostgreSQL to apply the changes:

systemctl restart postgresql

Also verify that your firewall only allows connections to PostgreSQL port 5432 from the Radiator host IP addresses. The pg_hba.conf setting controls authentication but does not replace network-level access control.

Step 3: Configure RadiatorDB Connection

On the Radiator host, create the file 20_radiatordb.radconf in the Radiator configuration directory (typically /var/lib/radiator/):

backends {
    radiatordb "mydb" {
        server "pg1" {
            host "192.168.1.20";
            port 5432;
            database "radiatordb";
            username "radiatordb_admin";
            password "r4d1at0rDB!secret";
        }
    }
}

Replace 192.168.1.20 with the IP address of your PostgreSQL host.

When Radiator starts, RadiatorDB automatically creates the database and the required SQL tables. No manual database or schema setup is needed.

Step 4: Configure Management Users for RadiatorDB Access

Management users need user.radiatordb_role set in the management authentication policy to access RadiatorDB collections. Without this, users receive 403 Forbidden when accessing RadiatorDB through the Management UI or REST API.

Use a jsonfile backend to store management users. Create management-users.json:

{
  "users": [
    {
      "username": "admin",
      "password": "secret",
      "roles": ["admin"],
      "privilege": "all"
    },
    {
      "username": "support",
      "password": "secret",
      "roles": ["support"],
      "privilege": "monitor"
    }
  ]
}

The role names are not fixed. They must match the roles block in your collection definitions in 20_radiatordb.radconf, where you configure which roles grant read or write access. Write access also gives the user read access to the collection. In the example above combined with configuration example in Step 6, admin has both read and write access to the users collection.

Configure the management authentication policy to map the roles from the JSON file into user.radiatordb_role:

backends {
    jsonfile "MANAGEMENT_USERS" {
        filename "management-users.json";
        query "FIND_USER" {
            mapping {
                user.username = doc | jsonpath("$.users[?(@.username == '%{aaa.identity}')].username");
                user.password = doc | jsonpath("$.users[?(@.username == '%{aaa.identity}')].password");
                user.radiatordb_role = doc | jsonpath("$.users[?(@.username == '%{aaa.identity}')].roles[*]");
                user.privilege = doc | jsonpath("$.users[?(@.username == '%{aaa.identity}')].privilege");
            }
        }
    }
}

The user.radiatordb_role assignment extracts all role strings from the user's roles array and makes them available for collection access control.

Step 5: Verify the Connection

Start Radiator and check the server log for a successful RadiatorDB connection message:

RadiatorDB::mydb INFO Connected to PostgreSQL (server=pg1 host=192.168.1.20 database=radiatordb)

If the connection fails, the log shows the error reason. Verify that PostgreSQL is reachable from the Radiator host and that the credentials and pg_hba.conf settings are correct.

You can also confirm the connection through the Management API:

curl -u admin:secret http://127.0.0.1:8080/api/v1/radiatordb/mydb

A successful response returns the list of collections configured for that backend.

Step 6: Define a Collection

RadiatorDB stores data in collections of JSON documents. Add a collection inside the radiatordb block in 20_radiatordb.radconf:

backends {
    radiatordb "mydb" {
        server "pg1" {
            host "192.168.1.20";
            port 5432;
            database "radiatordb";
            username "radiatordb_admin";
            password "r4d1at0rDB!secret";
        }

        collection "users" {
            name "Users";
            description "Managed user credentials";

            roles {
                read "support";
                write "ops";
                write "admin";
            }

            key {
                field {
                    name "Username";
                    type text;
                }
            }

            field "password" {
                name "Password";
                type password;
                required true;
                masked true;
            }
        }
    }
}

Each collection requires a key block with one or more fields that form the unique document identifier. Additional field blocks define the document structure exposed in the Management UI.

For details on collections, keys, and document structure, see the following articles:

• RadiatorDB - Overview of concepts, collections, and document format
• RadiatorDB REST API - Read and write documents through the management API
• RadiatorDB CLI - Manage documents from the command line
• RadiatorDB Backup - Export and import database backups

Step 7: Add RadiatorDB to the Management UI Sidebar

To make RadiatorDB collections visible in the Management UI sidebar, add a ui block to your configuration (for example in a file named ui_sidebar.radconf):

ui {
    sidebar {
        section "RadiatorDB";
        item "mydb" {
            url "/radiatordb/database?dbName=mydb";
            icon "Database";
        }
    }
}

The dbName query parameter must match the name used in the radiatordb block ("mydb" in this guide).

After making configuration changes, restart Radiator or trigger a configuration reload for the changes to take effect.

Multi-Master Setup

RadiatorDB supports multi-master replication by configuring multiple PostgreSQL servers. Each server gets its own server block:

backends {
    radiatordb "mydb" {
        server "node1" {
            host "192.168.1.20";
            port 5432;
            database "radiatordb";
            username "radiatordb_admin";
            password "r4d1at0rDB!secret";
        }

        server "node2" {
            host "192.168.1.21";
            port 5432;
            database "radiatordb";
            username "radiatordb_admin";
            password "r4d1at0rDB!secret";
        }
    }
}

RadiatorDB automatically configures logical replication between the PostgreSQL instances. Each PostgreSQL server must have the following settings in postgresql.conf:

wal_level = logical
max_replication_slots = 4
max_wal_senders = 4

Writes to any single instance replicate automatically to all other instances. Write conflicts are resolved using a last-writer-wins strategy.

Next Steps

After verifying the connection and defining collections, populate data through the REST API or the Radiator UI.