Hey Unraid Community! 👋

I've been running my Unraid server for a few years now, and like many of you, I've built up a pretty complex setup with dozens of containers, custom configurations, and specific network setups. Everything was great until my hardware died and I realized I had no good way to quickly rebuild everything.

After spending an entire weekend manually recreating my setup from memory and scattered notes, I decided to build something better.

What is Unraid Config Guardian?

It's a simple Python tool that automatically documents your entire Unraid setup for disaster recovery. Think of it as "Infrastructure as Code" for your homelab.

What it does:

• Scans all your running Docker containers

• Generates ready-to-deploy docker-compose.yml files

• Creates automated restoration scripts

• Documents your system configuration

• Masks sensitive data (passwords, API keys) for security

• Runs on a schedule to keep documentation current

The Problem It Solves

How many of you have ever thought: "If my server died tomorrow, how long would it take me to rebuild everything?"

Docker Hub: https://hub.docker.com/repository/docker/stephondoestech/unraid-config-guardian/

GitHub: https://github.com/stephondoestech/unraid-config-guardian

Documentation: https://github.com/stephondoestech/unraid-config-guardian/blob/main/README.md

Giving this a go now, while the appdata backup plugin does some of this - restoring data is the pain in the butt part. It'd be good if you could make a dedicated section in the readme for the "restore" aspects, steps to take etc.


edit: i see you've got a nice readme for the restore process within the container under backups. <3 For visibility, i'd politely ask this be added to github too. Thank you!

Edited August 28, 2025Aug 28 by Inch

Love this idea!

Unfortunately after initial run with practically default config I get "Docker not available", any ideas?

(I don't use Unraid default docker image format but the docker folder format if that helps)

Setting up cron job with schedule: 0 2 * * 0
Creating initial configuration...
Starting Unraid Config Guardian Web GUI on http://0.0.0.0:8080
Access via: http://your-unraid-ip:7842
INFO: Started server process [1]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
WARNING: Invalid HTTP request received.
WARNING: Invalid HTTP request received.
WARNING: Invalid HTTP request received.
WARNING: Invalid HTTP request received.
Docker not available, using mock data: 404 Client Error for http+docker://localhost/v1.47/images/a28adb3c8e0c7cec55c71b42f244a5d12b4391950845a524cfdcdf20d302a3ab/json: Not Found ("No such image: sha256:a28adb3c8e0c7cec55c71b42f244a5d12b4391950845a524cfdcdf20d302a3ab")

I am also having the same error as bristopher, same setup too, I use the folder setup. The only thing i changed from the default template was output directory

3 hours ago, Inch said:

Giving this a go now, while the appdata backup plugin does some of this - restoring data is the pain in the butt part. It'd be good if you could make a dedicated section in the readme for the "restore" aspects, steps to take etc.


edit: i see you've got a nice readme for the restore process within the container under backups. <3 For visibility, i'd politely ask this be added to github too. Thank you!

Can you do me a favor and open an issue in the repo? Love this idea and happy to implement it.

3 hours ago, bristopher said:

Love this idea!

Unfortunately after initial run with practically default config I get "Docker not available", any ideas?

(I don't use Unraid default docker image format but the docker folder format if that helps)

Setting up cron job with schedule: 0 2 * * 0
Creating initial configuration...
Starting Unraid Config Guardian Web GUI on http://0.0.0.0:8080
Access via: http://your-unraid-ip:7842
INFO: Started server process [1]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
WARNING: Invalid HTTP request received.
WARNING: Invalid HTTP request received.
WARNING: Invalid HTTP request received.
WARNING: Invalid HTTP request received.
Docker not available, using mock data: 404 Client Error for http+docker://localhost/v1.47/images/a28adb3c8e0c7cec55c71b42f244a5d12b4391950845a524cfdcdf20d302a3ab/json: Not Found ("No such image: sha256:a28adb3c8e0c7cec55c71b42f244a5d12b4391950845a524cfdcdf20d302a3ab")

Do you mind sharing your XML template or a screenshot of your setup? I’m looking now and I think /output expects it to be in that location but that’s an easy code fix.

A screenshot of the GUI error when you try to load the page would be helpful too.

Okay @bristopher and @Korosys I think I found the issue.

The way I'm doing the docker image data lookup didn't have error handing for when the images were deleted or unavailable. I've cleaned up the lookup code a bit and added better error handing so that should solve the issue you're both having. It now has better code to do the image data lookup and a fallback to parse the container config if that fails.

@Inch I updated the readme with your request too.

very promising app, clean and fast! Thank you for all your efforts. I submitted an enhancement request to also scan stopped dockers.

Edited August 29, 2025Aug 29 by JudasD

Can you add the version number of Unraid Config Guardian to the dashboard?

I'm quite sure sure i'm lame but there's no docker-compose in my unraid :-/ ?

@JudasD thank you for catching that! It’s a bug I introduced solving another issue. I plan to have a fix in the next day or two for that.

@kfonda absolutely! I’m thinking of throwing it in the header. It’ll match the latest available tag.

@dhstsw technically all your docker containers are compose under the hood. It’s just made easier to interact with in Unraid by using the GUI. When you do the restore Unraid Config Guardian simply leverages compose to rebuild your containers, but once completed is no different then going to the CA page and installing from there. Would it be helpful if I added some language explaining that to the readme?

1 hour ago, stephondoestech said:

@dhstsw technically all your docker containers are compose under the hood. It’s just made easier to interact with in Unraid by using the GUI. When you do the restore Unraid Config Guardian simply leverages compose to rebuild your containers, but once completed is no different then going to the CA page and installing from there. Would it be helpful if I added some language explaining that to the readme?

Yes, what i mean is:

From README.md

>4. Run: bash restore.sh

restore.sh checks if docker-compose is installed and then calls it.

Running from bash restore.sh (for bash i mean, a console on unraid itself), i get:



Unless i misunderstood something.

thanx.

Edited August 29, 2025Aug 29 by dhstsw

1 hour ago, dhstsw said:

Yes, what i mean is:

From README.md

>4. Run: bash restore.sh

restore.sh checks if docker-compose is installed and then calls it.

Running from bash restore.sh (for bash i mean, a console on unraid itself), i get:



Unless i misunderstood something.

thanx.

This is an absolutely valid callout and a missed use case on my part. Since XML templates for all user added containers are stored in /boot/config/plugins/dockerMan/templates-user I could do the following:

• add those as a zip to the backup called container-templates.zip as a backup file

• add an option to restore the templates to the boot location

• Update the restore script to restore the templates first then update the readme to instruct the user on how to add their containers back based on that

• Leave the docker-compose as a fallback with a warning that these won't be managed by the Unraid CA system

This seems like the most reasonable approach. Give me a few days to a week to put in this update as I really want to test this well. I'll likely bump this as a minor version update since it's somewhat new functionality.

46 minutes ago, stephondoestech said:

This is an absolutely valid callout and a missed use case on my part. Since XML templates for all user added containers are stored in /boot/config/plugins/dockerMan/templates-user I could do the following:

• add those as a zip to the backup called container-templates.zip as a backup file

• add an option to restore the templates to the boot location

• Update the restore script to restore the templates first then update the readme to instruct the user on how to add their containers back based on that

• Leave the docker-compose as a fallback with a warning that these won't be managed by the Unraid CA system

This seems like the most reasonable approach. Give me a few days to a week to put in this update as I really want to test this well. I'll likely bump this as a minor version update since it's somewhat new functionality.

I agree with this completely! Use the user XML templates first. Then ONLY use docker compose as a fallback or for the apps already installed thru docker compose.

12 hours ago, stephondoestech said:

Okay @bristopher and @Korosys I think I found the issue.

The way I'm doing the docker image data lookup didn't have error handing for when the images were deleted or unavailable. I've cleaned up the lookup code a bit and added better error handing so that should solve the issue you're both having. It now has better code to do the image data lookup and a fallback to parse the container config if that fails.

@Inch I updated the readme with your request too.

Thank you!! Looking forward to the update and using this!! My Unraid server always corrupts the flash drive every once and awhile and I've been dying for an all in one solution to rebuild Unraid just in case!

Edit: v1.0.3 update fixed it, thank you great work!

Edited August 29, 2025Aug 29 by bristopher

3 minutes ago, bristopher said:

Thank you!! Looking forward to the update and using this!! My Unraid server always corrupts the flash drive every once and awhile and I've been dying for an all in one solution to rebuild Unraid just in case!

It might not be showing in the UI yet but there is a new release out with a couple of fixes and small GUI updates. They were pretty quick to implement. You might have to force update until Unraid picks up the new image SHA.

I love the idea and appreciate your effort!

However in the current state it doesn't provide much additional use upon appdatabackup. It serves as a record for all the docker container settings which i could use to manually recreate all my containers, but with the restore of docker containers through docker-compose, the use of the docker interface options in Unraid will be limited after a restore, like missing shortcuts to the Webui and the console per container. Also shares, installed plugins and it's settings, virtual machines and all the user settings of Unraid itself are still missing in the backup, so it's not a bare-metal-restore tool yet. But it would be awesome if it would develop into that though.

Hello! I hope this can help me in my use case.

I have an old server set up the way I want it. I am getting a new outright replacement in the future. Drives and all.

Can I use this tool to back up all my configs on my old server so I can get up and running faster on the new one?

On 8/29/2025 at 6:22 PM, urbanracer34 said:

Hello! I hope this can help me in my use case.

I have an old server set up the way I want it. I am getting a new outright replacement in the future. Drives and all.

Can I use this tool to back up all my configs on my old server so I can get up and running faster on the new one?

@stephondoestech Could you please look at this post mentioned and tell me what you think? Thanks!

On 8/30/2025 at 1:22 AM, urbanracer34 said:

Hello! I hope this can help me in my use case.

I have an old server set up the way I want it. I am getting a new outright replacement in the future. Drives and all.

Can I use this tool to back up all my configs on my old server so I can get up and running faster on the new one?

In theory you should be able to, you'll still need to backup all your data and things like /appdata/

Hey everyone! Sorry I’ve been quiet, it’s been busy with the holiday weekend here in the US.

So quick update, I’ve received A TON of feedback on this service and I’m working through all of it. I’m in the process the creating issues for all of the things I plan to implement. I’ll be up front that I do not plan to implement every suggestion submitted, but there are a great many that I will.

For version 1.1.0 which I’m in the process of testing now I’ve added the following:

• configuration generation focuses on templates first then fallback to docker compose

• If templates can’t be restored then docker compose will be installed before being run

• Adding a flag to enable/disable docker compose restore

• Adding a GitHub action to create a PR in the Ibracorp repo each time the XML template is updated in the service repo to keep changes in sync

• Initial implementation of enacting with the Unraid API to better detect configuration changes

• Updating the readme to better reflect the services purpose (receiving feedback that this is unclear)

If your feedback isn’t listed here check the repo to see if an issue exists for it. I’m focusing on this for the next version as it addresses the most obvious pain points for users. Thank you all so much for your feedback and I’m looking forward to getting the next version out to y’all soon!

Quick update everyone! I'm still working through all the feedback (damn my pesky day job) and am actively working on making the implementation better. I just pushed version 1.0.4 out to production which does require a manual template update. In hindsight this should've been a minor version bump so I do apologize for that.

In order to have the container not run as root I've implemented the use of docker socket proxy. For this to work you MUST install the dockersocket container from the Apps page. You will need to add a variable to it called IMAGES and set the value to 1.

In the UnraidConfigGuardian container you'll want to remove the docker host path and instead add a variable called DOCKER_HOST and set it to the address of your dockersocket container. This will allow the service to run as a non privileged user while still getting the information it needs for the system. You will also want to update the PUID and PGID to 99 and 100 respectively. Lastly the container port needs to be updated to 7842as the previous value was causing an issue in the template validator.

Thank you again everyone for the continued feedback. I'm excited to keep working on this project and making it more useful with each update.

Hi, i reinstalled the docker with the new template and installed dockersocket but your Guardian shows me no available Dockers.

Is there something i have to change for the dockersocket? Sorry but i never used it before.

Hi guys,

the app stops after install, in the log the following issue:

"/entrypoint.sh: line 39: /config/config.yml: Permission denied"

Need to set something additionally?

I have followed the steps and its shows all my dockers in the webGUI but it doesn't pickup my hostname or unraid version.

I get the following error doesn't doesn't matter where I set the output directory when I try to run a backup

Last backup failed: [Errno 13] Permission denied: '/output/unraid-config.json'

Before the above error is displayed on the webui the logs for the Unraid Config Guardian App show the following

"POST /api/backup/start HTTP/1.1" 200 OK
"GET /api/backup/status HTTP/1.1" 200 OK

The Unraid Config Guardian App can see the previous backups I Made.

I Previously ran the App on my custom docket network, what networks are you running the app.

This is the notices when starting the docker socket app,not sure if the matters

[NOTICE]   (1) : haproxy version is 3.2.4-98813a1
[WARNING]  (1) : Exiting Master process...
[WARNING]  (12) : Proxy dockerfrontend stopped (cumulated conns: FE: 34, BE: 0).
[WARNING]  (12) : Proxy dockerbackend stopped (cumulated conns: FE: 0, BE: 1034).
[WARNING]  (12) : Proxy docker-events stopped (cumulated conns: FE: 0, BE: 0).
[WARNING]  (1) : Current worker (12) exited with code 0 (Exit)
[WARNING]  (1) : All workers exited. Exiting... (0)
[NOTICE]   (1) : Initializing new worker (11)
[NOTICE]   (11) : haproxy version is 3.2.4-98813a1
[WARNING]  (11) : missing timeouts for backend 'docker-events'.
   | While not properly invalid, you will certainly encounter various problems
   | with such a configuration. To fix this, please ensure that all following
   | timeouts are set to a non-zero value: 'client', 'connect', 'server'.
[NOTICE]   (11) : config: Empty global server state file '/var/lib/haproxy/server-state'.
[NOTICE]   (1) : Loading success.

The App completely breaks when trying try to add tailscale within the App as I did previously so I'm left that out with this version