9.1. Backing Up HUB Static Configurations

Warning

By default, the backup process includes only static configurations and selected database tables. Job and task-related data are not included unless a Full backup is explicitly requested.

Ngenea Hub provides a set of commands to efficiently back up and restore critical static configurations and selected database tables. It also provides a command to prune older backup archives according to a defined retention policy. This ensures quick recovery and minimal downtime during system upgrades or failures at a cost of reduced time to retain records.

These commands allow administrators to safeguard essential configuration data such as schedules, users, workflows, external targets, and spaces.

Two backup modes are supported:

  • ConfigOnly (default) – Backs up static configurations and selected configuration. Job and task history are excluded.

  • Full – Includes everything in ConfigOnly, plus job and task history in an additional archive.

Warning

Full backups include job history data, which can significantly increase the size of the backup files.

In environments with large job datasets, this may result in longer backup and restore times and increased storage usage.

ngeneahubctl backup --help

Usage: ngeneahubctl backup [OPTIONS] COMMAND [ARGS]...

  Backup and restore ngeneahub static configurations

Options:
  -T, --disable-tty       Disable pseudo-tty allocation
  --container-mount TEXT  Container mount path for DB
  --db-container TEXT     Name of the DB container
  --external-db           Use external database
  --help                  Show this message and exit.

Commands:
  auto     Export and Prune ngeneahub static configurations
  export   Export ngeneahub static configurations to a file
  prune    Prune ngeneahub static configurations
  restore  Restore ngeneahub static configurations from a file

9.1.1. Export

The backup process captures key Ngenea Hub configurations and selected database tables, providing a snapshot of key static configurations.

By default, the backup includes static configuration data only. If a Full backup is requested, job and task history data are also included.

To perform a backup, the Ngenea Hub database must be accessible. If using the internal database, ensure the database container is running. The container name is ngeneahub-db-1.

Service status can be validated with: ngeneahubctl status.

If using an external database, ensure the external postgres database service is running and reachable before performing the backup.

9.1.1.1. Command

ngeneahubctl backup export --help

Usage: ngeneahubctl backup export [OPTIONS]

  Export ngeneahub static configurations to a file

Options:
  -o, --output DIRECTORY  Location to store generated archive. Default
                          '$(PWD)'
  -f, --full              Create an additional file containing only the job history.
  --help                  Show this message and exit.

This command performs the following actions:

  • Database Dump (ConfigOnly – Default)

    Exports selected configuration-related tables into a SQL file, including:

    • Schedules

    • Users

    • Workflows

    • External targets

    • Global configurations

    • Spaces

    This mode excludes job history.

  • Full Backup

    When the --full flag is provided

    ngeneahubctl backup export --full <backup_path>

    In addition to the archive created using the ConfigOnly parameter, an additional archive is created containing job and task history data which includes:

    • Workflow Jobs and tasks

    • Settings Jobs

    • Job results and statistics

9.1.1.2. Configuration backup

Copies static configuration files from key directories into the ConfigOnly archive:

  • /etc/ngenea/postgres - PostgreSQL settings

  • /etc/ngenea/redis - Redis configurations

  • /etc/ngenea/rabbitmq - RabbitMQ configurations

  • /etc/ngenea/ngenea-client.conf - Hub client configuration

  • /etc/sysconfig/ngeneahub - Hub configuration

9.1.1.3. Archive creation

Packages the SQL dump and configuration files into a compressed archive. - ngeneahub_backup_<timestamp>.tar.gz - Static configurations and configuration database tables - ngeneahub_backup_jobhistory_<timestamp>.tar.gz - Job history tables

These archives are saved to the current working directory or to a directory specified by the -o or --output command-line option.

Note

Backups can also be created automatically:

9.1.2. Backup on Startup

When the Ngenea Hub starts up, a database backup is automatically created using the backup tool.

Backup type: Controlled via the ngeneahubctl sysconfig file /etc/sysconfig/ngeneahub using:

BACKUP_ON_START = Full | ConfigOnly | None

Full – Full database backup (including Job History)

ConfigOnly – Backup only configuration tables (default)

None – Skip backup on startup

Note

If BACKUP_ON_START=Full, the backup process generates two separate archives

  1. ngeneahub_backup_<timestamp>.tar.gz – Standard database and configuration backup

  2. ngeneahub_backup_jobhistory_<timestamp>.tar.gz – Job history backup

Backup location: Controlled via postgres_spool_dir in the sysconfig file. This defines where the backup files will be stored.

Note

The startup backup occurs before the backend applies database updates to ensure a consistent database snapshot.

9.1.3. Restore

Note

Depending on the scenario, a wipe may be required before restoring a backup.

The restore process reinstates the backed-up database tables and configuration files, returning the Hub to its operational state following a failure or upgrade.

To perform a restoration, Ngenea Hub must be fully operational.

Note

After performing a restoration, all services need to be restarted.

9.1.3.1. Command

ngeneahubctl backup restore --help

Usage: ngeneahubctl backup restore [OPTIONS] PATH

  Restore ngeneahub static configurations from a file

Options:
  -f, --full  Add an additional flag which restores job history
  --help  Show this message and exit.

9.1.3.2. Restore Modes

  • ConfigOnly Restore

    Restores selected configuration-related database tables and static configuration files including:

    • Schedules

    • Users

    • Workflows

    • External targets

    • Global configurations

    • Spaces

    This mode excludes job history.

  • Full Restore

    When the --full flag is provided

    ngeneahubctl backup restore --full <backup_path>

    This restores Job history related data which includes:

    • Workflow Jobs and tasks

    • Settings Jobs

    • Job results and statistics

This command performs the following:

  • Unpack the backup archive: Extracts the contents of the backup file.

  • Restore configurations: Copies the saved configuration files back into their respective directories, re-establishing the static system setup.

  • Truncate and reset tables: Clears the selected database tables, resetting them to ensure no conflicts with the incoming data.

  • Import the SQL dump: Inserts the backed-up data into the database, restoring Configuration tables (default) and Job history tables (when --full is used)

9.1.4. Prune

The prune command is used to remove old database backups based on the retention policy.

Retention setting: db_backup_retain_count

If not set (None), all backups are kept and pruning does not run.

9.1.4.1. Pruning process

  1. Removes backups exceeding the retention count

  2. Deletes the oldest backups first

  3. Only affects files in the configured db_backup_dir

  4. Logs: Output is sent to the systemd logs

9.1.4.2. Command

  ngeneahubctl backup prune --help

  Usage: ngeneahubctl backup prune [OPTIONS]

    Prune ngeneahub static configurations

  Options:
    --help    Show this message and exit.

Note

The prune operation can be executed manually or automatically as part of the auto backup process. See Auto Backup for details.

9.1.5. Auto Backup

Ngenea Hub provides a management command for automated backups

9.1.5.1. Command

ngeneahubctl backup auto --help

Usage: ngeneahubctl backup auto [OPTIONS]

  Export and Prune ngeneahub static configurations

Options:
  --help    Show this message and exit.

This command performs a 3-step process:

Export - Calls ngeneahubctl backup export to create a database backup

Prune - Calls ngeneahubctl backup prune to remove old backups according to retention settings

Report - Sends a report of the entire operation to the configured report target (if enabled)

Each auto backup creates a job in the Hub UI for the corresponding backup run. The job includes tasks for both the backup and prune steps, with detailed task results showing created and pruned backups.

Note

These Jobs cannot be re-submitted.

9.1.5.2. Configuration Settings

These are the supported backup configurations, which can be set via the /configurations API in the backend or through the Global Settings page in the UI.

Setting

Possible Values

Description

db_backup_enabled

True / False

Enable or disable database backups

db_backup_type

Full / ConfigOnly

Defines the backup type (default: ConfigOnly)

db_backup_dir

File path

Directory where backups will be stored

db_backup_schedule

Cron expression

Schedule for periodic backups (e.g., 22 2 * * *)

db_backup_retain_count

≥1

Maximum number of backups to retain

db_backup_report

True / False

Whether to generate and send a backup report

9.1.6. Scheduled Backups

Auto backups can also be scheduled using systemd service and timer. Database backups run as an external systemd service included with the ngenea-hub RPM.

Service config: /usr/lib/systemd/system/ngenea-hub-database-backup.service

Timer config: /usr/lib/systemd/system/ngenea-hub-database-backup.timer

The timer schedule is updated from the db_backup_schedule configuration which can be set via configurations API or through the UI. At the scheduled time, the service automatically executes ngeneahubctl backup auto command.