Hello everyone,

I would like to introduce my current project called borg-backup-ui and at the same time get some feedback from experienced Unraid plugin developers.

The goal of this plugin is to provide a complete web interface for Borg Backup directly on Unraid — without requiring additional external Python dependencies.

Features

At the moment the plugin already includes:

• Backup job management (wizard + execution)

• Storage / repository checks

• Backup history & reports

• Browse & restore

• Restore test functions

• Settings including system status & migration handling

Architecture

The application is based on a lightweight Python HTTP server and is intentionally designed to stay as independent as possible.

Runtime Structure

• UI / Server: borg_backup_ui.py

• API modules: api/

• Frontend: ui/

• Runtime code: runtime/

Included runtime components:

• runtime/lib/

• runtime/scripts/

• runtime/config/

• runtime/bin/borg/ (bundled Borg binary)

Target Structure on Unraid

Plugin Code

/boot/config/plugins/borg-backup-ui/

Runtime / Operational Data

/boot/config/borg-backup/

Including for example:

• config/backup.conf

• config/jobs/

• secrets/

• locks/

• scripts/

Logs, restore status information, and additional runtime data can optionally be moved to a configurable GLOBAL_DATA_DIR.

Service Integration

The plugin uses its own rc script:

plugin/rc.borg_backup_ui

Typical commands:

/etc/rc.d/rc.borg_backup_ui start
/etc/rc.d/rc.borg_backup_ui stop
/etc/rc.d/rc.borg_backup_ui restart
/etc/rc.d/rc.borg_backup_ui status

Logfile:

/var/log/borg_backup_ui.log

First Install & Migration

On first startup, all required directories are automatically created.

In addition, the plugin includes an idempotent migration system for existing installations:

• Migration of job metadata

• Migration of secrets

• Passphrase path adjustments

• Persistent migration state tracking

Project Goals

My main focus is on:

• easy usability

• transparent backup management

• minimal external dependencies

• clean integration into Unraid

• a long-term maintainable architecture

Feedback / Questions for Other Plugin Developers

Since this is my first larger Unraid plugin project, I would really appreciate some feedback:

• Which best practices should every Unraid plugin follow?

• Are there common pitfalls or mistakes to avoid?

• How do you handle updates, migrations, and rollbacks?

• Any recommendations regarding logging, security, or UI integration?

• What should be avoided to keep a plugin stable long term?

I’m looking forward to your feedback, criticism, and improvement suggestions 🙂

The screenshots are currently still in German — support for both English and German is planned.

19 hours ago, Thorsten said:

1. Which best practices should every Unraid plugin follow?

2. Are there common pitfalls or mistakes to avoid?

3. How do you handle updates, migrations, and rollbacks?

4. Any recommendations regarding logging, security, or UI integration?

5. What should be avoided to keep a plugin stable long term?

Forgive my bluntness, but this should not be a plugin. Docker containers are the preferred way of adding services to an unRAID server, and plugins should only be considered for things that cannot be containerized because they require direct access to the host os. Docker containers (on the unRAID platform) provide crucial benefits to both end users and developers. For end users they provide a means for controlling file access and resource allocation for services that is not available for bare metal plugins. Additionally they protect the stability of the core NAS functionality of unRAID by insulating services in containers. For the developer they address many of your questions above by allowing your service to run in its preferred environment without relying on the stripped down distro that unRAID runs on or having to handle the many versions of unRAID that are currently still in wide use (being essentially a network appliance many users rarely if ever update their systems). In the specific case of you proposed app, the fact that it runs its own webserver, interacts with borg (which i have long said also belongs in a container), and is python based (which does not belong directly on the host system) it is the perfect example of something which would be better served as a container. If the reason for making this a plugin is the want to directly integrate the ui with the unRAID webgui then something link this https://forums.unraid.net/topic/57109-plugin-custom-tab/ is a better solution.

Edited May 12May 12 by primeval_god

2 hours ago, primeval_god said:

Forgive my bluntness, but this should not be a plugin. Docker containers are the preferred way of adding services to an unRAID server, and plugins should only be considered for things that cannot be containerized because they require direct access to the host os. Docker containers (on the unRAID platform) provide crucial benefits to both end users and developers. For end users they provide a means for controlling file access and resource allocation for services that is not available for bare metal plugins. Additionally they protect the stability of the core NAS functionality of unRAID by insulating services in containers. For the developer they address many of your questions above by allowing your service to run in its preferred environment without relying on the stripped down distro that unRAID runs on or having to handle the many versions of unRAID that are currently still in wide use (being essentially a network appliance many users rarely if ever update their systems). In the specific case of you proposed app, the fact that it runs its own webserver, interacts with borg (which i have long said also belongs in a container), and is python based (which does not belong directly on the host system) it is the perfect example of something which would be better served as a container. If the reason for making this a plugin is the want to directly integrate the ui with the unRAID webgui then something link this https://forums.unraid.net/topic/57109-plugin-custom-tab/ is a better solution.

Thanks, that makes sense.

One reason I initially considered the plugin approach is that there are also existing Unraid plugins such as unBALANCE which run a background service / web UI and interact directly with the array.

My thinking was similar: backup and restore operations are very closely tied to Unraid paths, shares, disks, permissions, locks, logs, and the overall NAS workflow.

That said, I understand that Borg Backup UI is more like a full application than a small helper plugin, especially because it includes its own web server, Python code, and a bundled Borg binary.

So maybe the better long-term architecture could be:

a Docker container for the Borg UI backend/runtime

a small Unraid plugin only for native UI integration, launcher/settings link, and possibly lifecycle management

That would keep the actual service isolated while still offering a native Unraid user experience.

I appreciate the feedback — I think this is exactly the kind of architectural discussion I was hoping for.

7 minutes ago, Thorsten said:

Thanks, that makes sense.

One reason I initially considered the plugin approach is that there are also existing Unraid plugins such as unBALANCE which run a background service / web UI and interact directly with the array.

Dont quote me on this but the original unBalance plugin may actually predate the inclusion of docker in unRAID. That said these days it probably could be done within a container, though it does make use of one of the under-the-hood details of unRAID which might make path configuration confusing for users (that being the need to access both user and disk shares).

12 minutes ago, Thorsten said:

My thinking was similar: backup and restore operations are very closely tied to Unraid paths, shares, disks, permissions, locks, logs, and the overall NAS workflow.

I understand your thinking but i would disagree. I personally handle backup using a containerized version of urBackup. I map the parts of my array that require backup into it via read only mount points (including disk shares). It has dedicated rw mappings for is config, storage, and tmp locations. This ensures during normal operations it only has access to the parts of the system that it needs. The only complication is on restore at which point I have to either change the ro mapping to rw to do an inplace restore, or restore to rw directory and move the files.

22 minutes ago, Thorsten said:

a small Unraid plugin only for native UI integration, launcher/settings link, and possibly lifecycle management

I am not certain there are many if any examples of an architecture like this with a plugin front end and a container backend, however I think it is a great idea. Perhaps you can set the standard for split plugin/docker services.

That is actually one of the reasons why I am still not fully convinced that a pure container-based approach would fit the project well.

The application is not only intended to be a Borg web interface. It is also designed as an Unraid-specific backup orchestration tool that interacts quite deeply with the host system.

For example, when backing up the appdata directory, the application can automatically stop running Docker containers before the backup starts and then restart them afterwards based on their configured startup priority.

The same applies to VMs. The application detects currently running VMs, checks for logged-in users, sends notifications, waits for a configurable grace period, shuts the VMs down cleanly, performs the backup, and then starts the VMs again afterwards.

From my current understanding, implementing this inside a container would require rather extensive host integration, including access to Docker management, libvirt, Unraid-specific commands, notifications, sockets, and potentially privileged access.

At that point, the container would no longer be a simple isolated application container but would effectively become a host orchestration component with broad system-level permissions.

That is why I currently see the project as something slightly different from a typical standalone web application. It is evolving more into an Unraid-native backup orchestration system that coordinates backups together with Docker containers, VMs, shares, and host-level workflows.

I am still evaluating where the best architectural boundary should be, but this is one of the main reasons why I initially chose the plugin approach.

7 hours ago, Thorsten said:

The application is not only intended to be a Borg web interface. It is also designed as an Unraid-specific backup orchestration tool that interacts quite deeply with the host system.

For example, when backing up the appdata directory, the application can automatically stop running Docker containers before the backup starts and then restart them afterwards based on their configured startup priority.

The same applies to VMs. The application detects currently running VMs, checks for logged-in users, sends notifications, waits for a configurable grace period, shuts the VMs down cleanly, performs the backup, and then starts the VMs again afterwards.

Ah see I didnt catch that from your initial post, I read it as just a webui component for borg. That said all of my above points still stand. Putting everything in a plugin will require more maintenance effort long term.

Small development update for Borg Backup UI for Unraid:

The project has made good progress over the last iterations. The UI redesign is now visible across the main areas: Dashboard, Jobs, Storage, History, Reports, Browse & Restore and Restore Tests.
The interface is now more consistent, uses clearer location grouping and shows job/storage state in a more readable way.

The current focus is polish and operational reliability:

- clearer Unraid-focused branding

- improved Dashboard and job overview

- structured Restore Test planning and reports

- Browse & Restore with restore history

- better notification handling

- improved ntfy messages with cleaner titles and compact backup result details

Dashboard

Jobs

Storage / Repositorys

Backup History

Reports

Browse & Restore

Restore Tests (Planing)

Restore Tests (Reports)

Settings