Docker Stats Plugin for Unraid

A dashboard widget plugin for Unraid that visualizes real-time resource usage of your top 10 Docker containers.

Features

• CPU Usage: Monitor CPU load per container.
• Memory Usage: Track memory consumption.
• Visuals: Clean interface on the Dashboard tab
• Real-time: Updates every 3 seconds.

Installation

To install the plugin on your Unraid server:

1. Copy the Direct Link to the docker-stats.plg file in the root of this repository.
   • Usually: https://raw.githubusercontent.com/davemachado/docker-stats/main/docker-stats.plg
2. Go to your Unraid Web UI.
3. Navigate to the Plugins tab.
4. Click on Install Plugin.
5. Paste the URL and click Install.

Development

1. Modify code: Make changes in the source/docker-stats directory.
2. Build: Run ./build.sh <version> to package the versioned .txz into packages/ and stamp the version and MD5 into docker-stats.plg.
3. Test on a server: Run ./deploy.sh to copy the current build to your Unraid box and install it. Set UNRAID_IP to override the default (tower.local), e.g. UNRAID_IP=192.168.1.10 ./deploy.sh.

Releasing

Add a CHANGES entry for the new version in docker-stats.plg, above the previous one — Community Applications shows this to users, and the release is rejected without it:

###2026.08.01
 - What changed

Then run ./release.sh. It defaults to today's date, builds the archive, stamps docker-stats.plg, commits both, and creates the tag:

$ ./release.sh
Building docker-stats 2026.08.01...
  archive: packages/docker-stats-2026.08.01.txz
  md5:     a1b2c3...
Committed: Release 2026.08.01
Tagged:    v2026.08.01  (read from docker-stats.plg)

Pass an explicit version to release under a different date: ./release.sh 2026.08.02.

The tag is read back out of docker-stats.plg after stamping rather than derived from the date a second time, so the tag and the .plg cannot disagree. release.sh refuses to run if the changelog entry is missing, if the tag already exists, or if anything outside docker-stats.plg and packages/ is uncommitted — so the release commit only ever contains the build.

Finally, push the tag first, then main:

git push origin v2026.08.01   # CI builds and publishes the release
# wait for the Actions run to go green
git push origin main          # announces the update to installed plugins

Push the tag before main, not together. Installed plugins poll docker-stats.plg on main to discover new versions, but download the .txz from the release assets. If main advertises a version before its release exists, anyone who updates in that window downloads a URL that 404s. Pushing the tag first also gives you a free dry run: if CI rejects the tag, main never advertised anything and no user saw a broken version.

If CI does reject the tag, fix the problem, then delete and re-create it:

git tag -d v2026.08.01
git push --delete origin v2026.08.01

CI does not build the plugin. It checks that packages/docker-stats-<version>.txz exists, that the .plg declares the same version as the tag, that the .plg's MD5 matches the archive, and that a CHANGES entry exists for the version — then attaches both files to the release.

The archives in packages/ are committed on purpose. Rebuilding the plugin elsewhere does not reproduce the same bytes, for two independent reasons: BSD tar and GNU tar encode identical content differently, and git does not preserve file mtimes, which tar records. A CI-side rebuild would therefore hash differently from the MD5 published in the .plg, and every user would hit an MD5 verification failure on install. Committing the exact bytes that were hashed is what keeps the published checksum honest.

The constraint is that the archive you commit must be the exact one whose MD5 was stamped into the .plg — not that any particular machine builds it. Either macOS or Linux produces a valid package; what breaks things is regenerating the archive somewhere else after the fact.

Package format

The archive is a Slackware package: a tar rooted at / holding the real install paths, owned by root, named docker-stats-<version>-x86_64-1.txz.

./usr/local/emhttp/plugins/docker-stats/...

The -x86_64-1 suffix is load-bearing. pkgtools derive the package name by stripping the last three hyphen-separated fields, but only when the filename has at least four of them; otherwise the entire string becomes the name. Named docker-stats-2026.07.25.txz, the package name would include the version, so every release would look like a different package — upgradepkg installs each one as new rather than replacing its predecessor, and stale entries accumulate in the package database. Verified against Slackware 15.0 pkgtools.

No install/slack-desc or doinst.sh is needed; Unraid plugin packages do not ship them.

The .plg hands the downloaded file to upgradepkg --install-new --reinstall rather than unpacking it by hand, so the plugin registers in the package database (/var/log/packages, a symlink to /var/lib/pkgtools/packages on current Slackware) and appears in the diagnostics users attach to forum posts, and removepkg in the removal script does real work.

build.sh stages the tree under a temp directory and sets ownership with tar flags that differ between implementations: --uid/--gid/--uname/--gname on bsdtar (macOS), --owner/--group/--numeric-owner on GNU tar (Linux). Each rejects the other's spelling, so the script picks based on tar --version.

Note that the version is a date, so there can be only one release per calendar day.

License

MIT