Docker on Unraid, built on compose files

Version 00.02.00 · changelog

Why this exists

Unraid describes containers in its own template format. Almost nothing else does. When a project publishes its setup — and nearly all of them publish a compose file — you cannot just use it: you retype it into a template, field by field, and hope you read it right.

The obvious fix is to run compose files directly. That works right up until you want to change a port, and find yourself editing indented text where one stray space breaks the file.

StaXX takes the compose file as it is and draws it as a form. Change the port in a box. The file underneath stays an ordinary compose file that still runs anywhere.

What it does

• Paste in a project's own compose file and it runs — no retyping into a template, no conversion step.
• Never read a line of it if you don't want to. Twenty-odd groups of settings — ports, folders, variables, health checks, start-up order — as ordinary form fields, with the file beside them if you prefer. The author's own comments become the help text next to each box.
• Change things without the fear. There is an Undo button, every save is kept, and every image that has actually run is kept, so a bad decision is one click back.
• Bring in what you already run. One window lists your existing Unraid apps, Compose Manager projects and loose containers, and imports them as copies — the originals stay put, and one click puts them back.
• Search 3,700 apps without leaving the page. Community Applications, Docker Hub and the images already on your server; pick one and get a compose file to look over before anything starts.

The 60-second start

Copy this address:

https://raw.githubusercontent.com/quadcom/Staxx/main/staxx.plg

In Unraid, go to Plugins → Install Plugin, paste it in, and press Install. That is the whole of it. You get a plugin Unraid looks after like any other: it survives a reboot, it appears on your Plugins page, and it will tell you when there is a newer version.

You do not need Community Applications for this, and StaXX is not in it — see Limitations.

Open Docker → Stacks. The first thing it does is ask where it should keep its data — one folder holding your stacks, the zips of any you remove, and its own settings. It suggests a sensible place and explains the choice; take the suggestion if you are in a hurry.

After that, make a folder inside the stacks folder of the place you chose, drop a compose file in it, and it is there. Or press Apps and pick something.

New to the page? The user guide explains what you are looking at.

To remove it again, use Remove on the Plugins page. Your settings and your stacks are left alone; deleting the data store folder is a separate, deliberate act.

A tour of what's here

Every item below has its own page in the user guide — enough here to see whether StaXX does what you need.

• The stacks page shows every container, with live figures, health, update state and which ports you can actually reach at a glance — hover an update pill to see both versions, when it was last checked and when it is next due; see what every mark means.
• On a tablet-sized screen, the list becomes a row of cards instead of a squeezed table, so everything stays readable without turning the device sideways.
• The editor shows one file three ways — form, file, or both side by side — with the author's comments turned into help text; see editing a stack.
• Health checks can be worked out for you: where nothing is watching a running container, StaXX finds a real question to ask that image, tries it inside the container first, and tells you what the answer would actually prove — see letting StaXX work out a health check.
• One house layout puts every file in the same order as it arrives, so your stacks all read the same way. Order only — nothing you wrote is rewritten, and comments stay with what they annotate; see tidying a file.
• Adding an app searches Community Applications, Docker Hub and your own server's images, and hands you a compose file to check before anything starts; see adding an app.
• Starting from scratch gives you a working skeleton from nothing but a name; see making a stack from scratch.
• Bringing in what you already run copies your existing Unraid apps, Compose Manager projects and loose containers, leaving the originals untouched; see bringing in a container.
• Folders group stacks that belong together and can be started, stopped or updated as one; see working with folders.
• Passwords and their scrambled form are generated for you, in the box that needs them; see passwords and hashes.
• Hiding your values blanks out anything marked secret so a stack can be screenshotted safely; see hiding your values.
• Checking for updates compares your images against their registries on a schedule you set; see checking for updates.
• Going back keeps every saved file and every image build that has run, so a bad change is one click undone; see recovery and redundancy.
• A safety copy of every stack lives on the flash drive too, now including its values file, so restoring one hands back a complete stack rather than one missing its settings.
• Sharing a stack exports a copy with your passwords, keys and paths taken out, ready to drop onto somebody else's StaXX; see sharing a stack.
• The settings panel is where almost everything about StaXX lives — where it appears, where your data is kept, icons, updates and sign-ins, with a picture of each option so you can see what you're choosing before you click it; see the settings panel.

What it promises

1. Never require non-standard syntax. A file StaXX writes runs unmodified anywhere Docker Compose does.
2. Never lose what the author wrote. Comments, shortcuts, values and intent survive an edit. A file that is genuinely wrong gets fixed, and you are told what changed.
3. Degrade gracefully. A file with no extras still produces a usable form.
4. Own the render. Layout and controls are drawn by StaXX, not injected into another page.

Limitations

• In beta. The core is settled and in daily use, but expect the occasional rough edge, and read the changelog before updating.
• Requires Unraid 7.2 or later, and Docker Compose already on the server — StaXX does not install it.
• Graphics figures cover Intel and AMD cards; Nvidia shows none, though a container given an Nvidia card is still labelled as such.
• Without a Docker Hub read-only token, update checks are limited to roughly ten images an hour.
• A stack has to be started by hand once before it can start at boot.
• Getting an archived stack back means unzipping it yourself.

Configuration (optional)

Everything here has a switch on the settings page, so this is reference only. Settings live in staxx.cfg in your data store, except three lines that stay on the flash drive so they are readable before the array starts — see where StaXX keeps its things.

CRYPT_MODE decides whether the password-hashing helper stays running (always) or starts only when needed (ondemand). The PWGEN_* keys are the password generator's own remembered choices, set from its panel rather than here. Comments in this file must start with a semicolon.

For contributors

The plugin is plain PHP and browser JavaScript with no client-side libraries, talking to the page through a single endpoint. src/staxx/ mirrors the install paths on the server; docs/ and schema/ describe the file format StaXX reads and writes.

Licence

GPL-2.0, matching unraid/webgui.

Prior art

Studied while scoping this. None of their code is used here.

• Compose Manager Plus — compose engine, header-menu toggle
• FolderView3 — collapsible grouping
• unraid-plugin-composerize — template → compose conversion