# Backup Manager Extension
This article describes the Backup Manager extension, which enables scheduling, encryption and replication of EasyDCIM application backups to remote SFTP and S3 storage. It explains how to configure automatic backups, define storage destinations, manage retention, monitor backup status, download backup files and prepare restore commands from the admin area. Read this article before relying on Backup Manager for disaster recovery, especially the sections about retention, encryption and the restore workflow.
# About
Backup Manager extends the EasyDCIM backup functionality by providing a graphical interface for scheduling, monitoring and managing backups. The command-line Backup Guide describes how to create and restore backups manually with easydcim-control. Backup Manager uses the same backup mechanism, but automates the process and supervises the full backup lifecycle.
After the backup policy is configured, the extension runs backups according to the selected schedule, copies them to one or more remote destinations, encrypts them when required, applies retention rules and displays the current backup status in the admin area.
Every backup is created on the host and stored in a separate timestamped directory under /opt/backups/app/. Each backup contains a backup.json manifest file with information about the files included in the backup, their sizes and checksums. Backup Manager registers each backup in the database, stores information about its components — the SQL database, application files and InfluxDB time-series data — and tracks each remote copy that has been uploaded.
Backup Manager is used to orchestrate, replicate and monitor backups. It is not a one-click rollback tool. Backup creation can be automated, but restoring a backup remains a manual action performed on the host, because it overwrites live data. The following sections describe both workflows.
# Features
- Scheduled backups on a daily, weekly or monthly cadence, with a configurable run time and day
- On-demand Backup Now runs that execute immediately, outside the schedule, with live per-stage progress
- Selectable components — the SQL database, the application files archive, and the InfluxDB data
- Off-site replication to multiple remote destinations using SFTP or S3-compatible object storage
- Optional client-side encryption with age (opens new window), applied before any copy leaves the server
- Independent retention policies for local copies and for each individual remote storage
- A complete backup history, with per-storage upload tracking, a job timeline and a file-level manifest
- Flexible download options — a single
.tararchive, individual files, or fetching a remote copy back on-site - A guided restore workflow that generates the exact, copy-ready commands to run, including decryption commands
- Granular deletion options: local files only, a single remote copy, all copies, or the database record only
- Pre-flight readiness checks and a health banner with disk-capacity information
- Automatic discovery and import of pre-existing backups found on disk
# Dashboard
To open the extension, navigate to Extensions → Backup Manager in the admin menu. The dashboard provides an overview of the backup status, the next scheduled backup, configured storage destinations and current disk usage.
At the top, a health banner summarizes the overall state. Directly below it, KPI tiles display the time of the last successful backup, the next scheduled run, the number of active storage targets and current disk usage on the host. Below the tiles, the dashboard displays the backup configuration form and two widgets with storage destinations and recent backups.
The health banner is color-coded so that problems are easy to identify. It is green when scheduled backups are enabled, at least one storage target is configured and a recent successful backup exists. It turns red when no recent successful backup can be found or when the configuration is incomplete, for example when encryption is enabled but the age binary is not available on the host. A stale most-recent backup, older than the freshness threshold, is also marked.
The Disk usage tile shows values collected from the host. Because the application runs in a container and cannot directly inspect the host backup directory, disk usage is based on a periodic host-side measurement. The value reflects the space used by backups under /opt/backups/app/. The same measurement is used for capacity checks and for the size estimates displayed next to backup components in the configuration form.
From the dashboard's Actions menu, you can start a backup immediately or run the pre-flight checks. Administrators with the appropriate permission can also view and edit the configuration form described below. Administrators with read-only access can view the dashboard without changing the configuration.
# Configuring backups
The configuration form defines the backup policy. It is divided into four sections: Schedule, Components, Retention and Encryption. When the configuration is saved, the host schedule is updated automatically, so the cron configuration on the server matches the settings displayed in the panel.
Schedule. Enable or disable automatic backups, choose a frequency of Daily, Weekly or Monthly, and set the time of day when the backup should run. For weekly and monthly frequencies, you also choose the day: a weekday or a day of the month between 1 and 28. A live preview displays the configured schedule together with the corresponding cron expression.
Components. Select which parts of EasyDCIM should be included in each backup: the SQL database dump, the application files archive and the InfluxDB time-series data. Each option displays an estimated size based on recent backups, so you can compare backup completeness with backup size and transfer time. At least one component must be selected.
Retention. The Keep local value defines how many of the most recent backups are kept on the host disk. When this number is exceeded, the oldest local copies are removed automatically. Local and remote retention are managed separately. Remote retention is configured per storage target, as described in Storage targets.
Encryption. Optionally encrypt every backup with a passphrase before it leaves the server, as described in Encryption. The passphrase must be entered twice for confirmation. After a passphrase is saved, both fields display a masked placeholder instead of the secret. Leaving the placeholder unchanged keeps the existing passphrase. Entering a new value replaces it.
After saving the form, Backup Manager validates the configuration, saves the settings, regenerates the host cron schedule and records the change in the activity log.
# Storage targets
Storage targets are remote destinations to which backups are replicated. At least one remote copy should be configured to protect backups against loss of the host. Backup Manager supports the following storage types:
- SFTP — any SSH/SFTP-accessible server. You provide the host, port, username, base path where backups will be stored, and either a password or a private key for authentication.
- S3 — Amazon S3 or any S3-compatible object storage. You provide the bucket, access key and secret key, together with either a region or a custom endpoint. A custom endpoint is typically used for self-hosted S3-compatible storage.
To add a destination, open the storages list and create a new storage. After selecting the driver, the connection fields are adjusted to match the selected storage type. You can enable or disable the target, define the Keep remote value, which controls how many copies are retained on that storage, and use the Test Connection button to verify the credentials before saving.
Each storage can be enabled, disabled, tested, edited or deleted. The storage name cannot be changed after it is created, so historical upload records remain clear. A storage that still contains backup copies, or has an upload in progress, cannot be deleted until those copies are removed. Disabling a storage excludes it from future backups, but does not remove existing copies.
# Running a backup now
The Backup Now action starts a backup immediately, independently of the configured schedule. This is useful before database migrations, upgrades or other maintenance operations. The components and encryption settings are taken from the saved configuration. The dialog only asks where the backup should be sent and, optionally, why it is being created.
In the dialog, choose the storage targets to which the backup should be uploaded. All enabled targets are selected by default. You can also enter a short reason for the run, which is stored with the backup for later reference.
After confirmation, the dialog displays live progress for each stage: Running, optional Encrypting when encryption is enabled, Uploading, Verifying and Succeeded. The backup is saved in the history as a manual backup and counts toward local retention.
If all storage targets are cleared before starting, the backup still runs and is kept locally only. No upload is performed. If another backup is already in progress, Backup Manager displays the current progress of that backup instead of starting another one.
# Backup history
The History view lists all backups registered by Backup Manager. Each entry displays its status, source, components, size and storage targets. The source shows whether the backup was created by the schedule, manually, by API or imported from disk.
The status indicates the current stage of the backup lifecycle. Backups can have the following processing statuses: Pending, Running, Encrypting, Uploading, Verifying or Importing. After processing is finished, the status changes to Succeeded, Partial or Failed. A Partial status means that the backup was created successfully, but at least one remote upload failed.
Opening a backup displays its detail page. This page includes the job timeline for backup creation, encryption, uploads and verification, with links to the related logs. It also displays the status of each remote copy and available actions, such as retrying a failed upload or sending the backup to additional storage targets. The file-level manifest lists every file included in the backup, together with its size and SHA-256 checksum.
# Downloading a backup
The Download dialog allows you to download a recoverable copy of a backup. The available options depend on where the backup files are currently stored.
If the files are still available on the host, you can download the whole backup as a single .tar archive or download individual files directly. If the only available copies are stored remotely, you can first fetch one copy back into the local backup directory. A progress indicator displays the transfer status. After the copy is available locally, archive and individual-file downloads become available.
If local files already exist, fetching a remote copy requires confirmation before overwriting them. Downloaded files are provided exactly as they are stored. If the backup is encrypted, the downloaded files remain encrypted and must be decrypted with the configured passphrase before they can be used. The restore workflow provides the required decryption commands.
# Restoring a backup
Restoring a backup is a manual procedure because it overwrites the live database and/or application files. The Restore Guide does not perform the restore automatically. It prepares the required files locally and generates copy-ready shell commands that must be reviewed and executed on the host.
The restore window guides you through the process. First, it allows you to prepare the files locally by fetching them from remote storage if they are not already present on the host. It then displays the local path where the files are staged and lists the manifest, including information about encrypted files. Finally, it displays the commands to run. For encrypted backups, decryption commands using age are displayed first, followed by the easydcim-control restore commands for the database, application files and InfluxDB data. Each command block can be copied with one click.
Because the commands affect live data, run them carefully and stop services where required. The warning at the top of the restore window repeats this information. The restore commands are the same easydcim-control commands documented in the Backup Guide, so the panel workflow remains consistent with the command-line workflow.
# Managing and deleting copies
Backup Manager provides separate actions for uploading, retrying and deleting backup copies. Each action indicates what data will be affected:
- Send to storage — upload an existing local backup to one or more additional storage targets. Use this option to add another off-site copy or restore a copy on a destination from which it was previously removed. The backup files must be available locally.
- Retry upload — retry a single upload that previously failed or was removed, without creating the backup again.
- Delete remote copy — remove the backup from one storage only. The database record and all other copies are retained, and the backup status is recalculated. If the remote deletion cannot be completed, the action reports the failure.
- Delete local files — remove the on-host copy while keeping the database record and any remote copies. The backup becomes remote-only.
- Delete everywhere — remove local files, all remote copies and the database record in one action.
- Delete from database — remove the database record and its upload entries. Optional switches allow you to also remove local files and remote copies when they exist. The action is blocked while the backup is in progress.
If a backup database record is removed but the files remain on disk, the backup is automatically registered again during the next discovery run. It is imported as a local-only backup.
# Encryption
When encryption is enabled, Backup Manager encrypts backup files with age (opens new window) using the configured passphrase. Encryption is performed before any copy is uploaded to remote storage. Encrypted files receive the .age suffix and the backup manifest is updated to reference the encrypted files. If a file is already encrypted, it is reused instead of being encrypted again.
The passphrase is required to decrypt and restore encrypted backups. Store it in a safe location outside the EasyDCIM server. Losing both the passphrase and the EasyDCIM APP_KEY makes encrypted backups unrecoverable. When encryption is enabled, pre-flight checks verify that the age binary is available on the host.
# Pre-flight checks
The Pre-flight action runs readiness checks before a backup is created. It verifies that scheduled backups are enabled and that sufficient disk space is available for the next backup. The expected size is estimated from recent backups. When encryption is enabled, the check also verifies that the age binary is available on the host.
Each check returns a pass, warning or failure status with an explanation. The dashboard displays the result of the most recent pre-flight check.
# How it works
Backups are created on the host and stored under /opt/backups/app/. Each backup is saved in a separate timestamped directory and contains a backup.json manifest file describing its contents. Long-running operations, such as creating backups, encrypting files, uploading copies and fetching remote copies, are handled by background jobs. This allows the panel to remain responsive while progress is displayed.
A periodic discovery process keeps the panel synchronized with the files available on disk. It handles the following cases:
- Scheduled backups, produced by the host's cron, are registered automatically and their copies are uploaded to the enabled storage targets.
- Any other backup directory found on disk — for example one re-synchronized from another server, or one whose database record was previously removed — is imported as a local-only entry and is not re-uploaded.
This separation ensures that new scheduled backups are registered and replicated automatically, while existing backups that reappear on disk are not uploaded again without an explicit action.
# Permissions
Access to Backup Manager is controlled by two permissions. The view permission allows an administrator to open the dashboard, history, storages list and logs, and to inspect backups in read-only mode. The manage permission is required to change the configuration, run backups, manage storage targets, and perform download, restore and deletion actions. An administrator with only the view permission can see the same information, but cannot perform actions that modify backups or configuration.