Spug 4.1: an agent-free ops panel that ships as one Docker image, with FUSE privileges attached

One container holds the back end and the built web UI

Spug calls itself agent-free: you do not install a daemon on each managed server. Everything you run sits in the control panel. The all-in-one image bakes in the Django back end, the compiled web UI and every runtime dependency, so a container needs no network access to start. That differs from the older docs/docker route, which downloads the code on first start. Images publish as openspug/spug and ghcr.io/openspug/spug for amd64 and arm64.

The Dockerfile builds the web UI once on the native build platform with node:20-bookworm-slim, because static output is identical across architectures, then compiles mysqlclient and python-ldap in a python:3.11-slim-bookworm stage so compilers stay out of the final image. A multi-arch build from source looks like this:

docker buildx build --platform linux/amd64,linux/arm64 -t spug:dev .

Builders in mainland China can pass PIP_INDEX_URL and NPM_REGISTRY build arguments to point at local mirrors such as the Aliyun PyPI mirror and registry.npmmirror.com.

Docker older than 20.10.10 fails on the bookworm base

The quick start requires Docker 20.10.10 or later with the Compose plugin, and the reason is specific. The runtime image is based on Debian bookworm, whose newer glibc uses the clone3 syscall. Older Docker engines ship a default seccomp profile that rejects clone3. The entrypoint detects that situation, and the Dockerfile notes that bullseye, which avoided the problem, is archived.

The consequence is that a long-lived server with an old Docker package cannot run the current image, and there is no older base to fall back to. Check docker version before you plan the install. With a current engine, the documented start is three commands:

curl -fsSLO https://raw.githubusercontent.com/openspug/spug/4.0/docker-compose.yml
docker compose up -d
docker compose logs spug | grep password

Note the 4.0 in that URL: the repository's default branch is named 4.0 even though the image tag in the Compose file is 4.1.

The admin password is printed to the container log

On first start, Spug generates a password for the admin account and writes it to the log, which is why the third quick start command greps for it. After that you open http://<your-server>/ and log in as admin. Anyone who can read docker logs on that host can read the initial password, so change it after the first login or set it up front. The Compose file carries a commented line for that:

# SPUG_ADMIN_PASSWORD: change-me    # first admin's password; a random one is printed to the log if unset

The database password needs the same attention. Both MYSQL_PASSWORD on the spug service and MARIADB_PASSWORD on the db service default to spug.cc through ${SPUG_DB_PASSWORD:-spug.cc}. That is also the password of the public demo at demo.spug.cc, where the admin login is admin with password spug.cc and data resets every hour. The comment says the database is reachable only from the spug container, but a known default is still a default: export SPUG_DB_PASSWORD before the first docker compose up -d so both services start with your value.

File distribution needs SYS_ADMIN, /dev/fuse and an unconfined AppArmor profile

Two features mount a source host with sshfs over FUSE: distributing files from one host to many, and the pipeline data transfer node. To make that work without privileged mode, the Compose file grants the container three things: cap_add with SYS_ADMIN, the /dev/fuse device, and security_opt apparmor:unconfined.

That is a meaningful grant. SYS_ADMIN is a broad capability, and dropping the AppArmor profile removes a layer of confinement from a container that already holds credentials for your fleet. The Compose comments say to remove all three settings if you do not use those two features. If your security policy forbids them, plan on losing host-to-host file distribution and the data transfer node; file upload and download through the browser and the other pipeline nodes are separate features. Decide this before rollout, because adding the capabilities later means editing the Compose file and recreating the container.

Port 80, TZ and two named volumes decide the day-two behavior

The spug service publishes 80:80. If something already listens on port 80, change the left side, for example to 8080:80. TZ defaults to UTC and drives scheduled tasks and timestamps, so a cron job you configure in the Task Planning module for 02:00 fires at 02:00 UTC unless you set TZ to a zone such as America/New_York or Europe/Berlin. The db service runs mariadb:10.11 with utf8mb4 and the utf8mb4_unicode_ci collation, and the spug service waits for the database health check before starting.

Data lives in two named volumes, including spug-data mounted at /data. Upgrading is a pull and a restart, quoted from the Compose header:

docker compose pull && docker compose up -d

The image line reads openspug/spug:4.1, a minor-version tag. The comment suggests pinning an exact version such as 4.1.1 if you prefer. Without that pin, a pull moves you to whatever the 4.1 tag points at.

A single SQLite container for evaluation only

To look at Spug without the MariaDB container, one command starts it on SQLite:

docker run -d --name spug -p 8080:80 openspug/spug:4.1

The password comes from docker logs spug | grep password. The command mounts no named volume, so treat it as a throwaway for a quick look. For anything you intend to keep, use the Compose file. Upgrades and other install methods sit in the installation guide at ops.spug.cc.

If you want to compare against the source requirements, the README lists Python 3.8+, Django 4.2, Node.js 18+, React 16.13 and Redis 5.0+. The image itself builds with Python 3.11 and Node 20. The repository holds spug_api, spug_web and a second front end directory, spug_web2.

Releases, pipelines and the modules behind the menu

Host Management groups hosts, imports them from cloud providers or an Excel file, and checks connectivity in batch. Batch Execution runs parameterized commands with reusable templates and keeps history. Credential Management stores passwords and private keys once and shares them across hosts. Build and Deploy supports custom builds with a review flow, canary release and rollback.

Pipelines chain parameter, build, remote command, data transfer, data upload and notification nodes, with conditional branches and a live console. Notification nodes cover DingTalk, Feishu, WeChat Work and Push Assistant, a separate message platform from the same team. Monitoring checks sites, ports, processes, ping and custom scripts, and the Alarm Center sends by email, WeChat, DingTalk, WeChat Work and Feishu. The notification list leans toward Chinese platforms, so teams that rely on other chat tools should check the alarm methods against their stack. Permissions are role based with LDAP login and MFA, and the UI switches between English and Simplified Chinese.

Spug Cloud does not exist yet, and the code is AGPL-3.0

Spug Cloud would host the control panel and connect to your servers over SSH at a planned $4.9 per server per month, but it is being researched and is not available. The only action today is joining a waitlist. Self-hosted Spug remains free and open source, so if you need Spug now, you are the one running and backing up the panel.

The license is AGPL-3.0, not a permissive license. Read its terms before modifying Spug for a service other people use over a network. The project is active: v4.0.1 and v4.1.0 were both tagged on 2026-10-10, v4.1.1 followed on 2026-10-12, and the last push was on 2026-10-27. Issues are accepted in English or Chinese.

Editorial conclusion

Spug fits a small operations team that wants host inventory, batch commands, releases with rollback, scheduled tasks and alerting in one self-hosted panel, with English and Chinese UIs. It does not fit anyone who wants a hosted service today, since Spug Cloud is only a waitlist, or who cannot grant a container SYS_ADMIN and /dev/fuse and still needs file distribution. Before going live, set SPUG_DB_PASSWORD and SPUG_ADMIN_PASSWORD, pick the TZ value, and pin an exact image tag such as 4.1.1.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. openspug/spug on GitHub
3. Project website
4. README
5. Releases