Skip to content
Ferdinand99Public

About

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

68 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Wise Wren

Keeps your Docker containers up to date, without surprises.

License: AGPL-3.0 Website

Status: early release (Docker images only). Wren lists what runs on each server (containers, Unraid template containers, Compose stacks and script-updated stacks), checks for new versions and updates what you approve, now or at a time you choose, with a snapshot, a health check and an automatic rollback. Automatic updates inside a window, the Vigilant Vole integration (maintenance windows and monitor-based health checks), ~40 notification channels, a REST API with OpenAPI and MCP tools, in 26 languages. It is tested on Unraid; other Linux Docker hosts are best-effort, btrfs subvolume snapshots are untested on real pools and ZFS uses plain copies. The translations are unreviewed drafts. Installers and static binaries come later. The design is in docs/design.md; to build and run it, see docs/development.md.

Wise Wren ("Wren") keeps the Docker containers on your servers up to date. It checks for new versions on a schedule you choose, tells you about them, and updates only what you approve, or what you have explicitly allowed it to update on its own.

Today, keeping a home server current often means a manual check every day. Unraid's update button covers containers made from its templates, but not Compose stacks or apps that update with a vendor's own script. Other tools either only notify (Diun, What's Up Docker) or update blindly (Watchtower). None of them pause your monitoring, take a snapshot first, check health afterwards and roll back.

What it does

  • Notify, approve or automatic. Each server has a default mode and each target can override it. Approve is the default: one click updates now, or at a time you choose.
  • Scheduled updates. Approve during the day, update tonight. A scheduled update shows as planned maintenance in Vigilant Vole ahead of time.
  • Safe updates, every time. Each run goes through the same steps:
    1. preflight: the new image is pulled before anything stops;
    2. a maintenance window opens in Vigilant Vole;
    3. the target stops gracefully;
    4. a snapshot of its data is taken;
    5. the update runs;
    6. a health check: the containers are healthy and the linked monitors stay up;
    7. on failure, an automatic rollback of the image or Compose files and the data;
    8. the window closes and you get the result.
  • Notifications through the same ~40 channels as Vigilant Vole, from ntfy on your phone and the Hedgerow app to email and Discord. One per new version, with a digest option.
  • One Wren, several servers, through a small agent on each.

Three kinds of targets

Kind Example New version means
Containers, including Unraid template containers nextcloud The image in the registry has changed
Docker Compose stacks immich Any of the stack's images has changed
Script-updated stacks Fluxer, updated with the vendor's installer A source such as GitHub releases reports a newer version

Wren never changes anything you haven't allowed

With automatic updates off, which is the default for every server and target, Wren updates nothing on its own. Automatic updates only run inside a window you set, and any container or stack can be excluded. An approval is for one version: if a newer one appears before it runs, Wren asks again. Scripts are defined on the agent (built-in presets, or its own agent.toml), and Wren can only ask for them by name, so it can never become a remote shell. The agent decides last: it updates only what its own agent.toml [updates] allows (no allow list, no updates), keeps its own record of the runs it did (a rollback only undoes the newest update it ran, once), never accepts a shorter health check or fewer snapshots than it requires, and talks to Wren over https:// unless Wren is on your own network.

Admins set what each agent may do in Wren's web UI (no TOML to edit): the agent checks every setting against hard limits of its own (folders only inside what is mounted into it, never system folders, scripts only from its built-in presets) before it applies it, and widening changes notify your channels. Lock an agent with WW_AGENT_LOCKED=1 and only its local agent.toml counts.

From 0.10 Wren can also update its own agents, but only where the host's owner switches that on locally (WW_AGENT_SELF_UPDATE=1), only to Wren's own version and only from the official image, with a rollback if the new agent can't reach Wren (Agent self-update).

Notifications in the Hedgerow app

The Hedgerow app on your iPhone can show Wren's notifications as push notifications, with no account and no other service to run.

  1. Under Settings → Notifications, add a channel of the kind Hedgerow app. It has no settings. It gets what every channel gets: new versions (one by one, or as a digest), the result of every update run and agents that go offline or come back. Only one Hedgerow app channel can be active at a time.
  2. In the Hedgerow app, open the connection to your server and turn on Varsler (notifications). The app registers itself with your server, and nothing is pushed to it before that.

Push is off until an admin adds the channel: with no active Hedgerow app channel the server refuses to register devices. A read-only API token is enough for the app. Send test on the channel shows an error until at least one device has registered. Like for the other channels, a notification that could not be sent is logged and not sent again.

What leaves your server is only a random reference. Wren keeps the text of each notification (“nextcloud on Tower is updated”) for 24 hours and sends the Hedgerow push relay (pigeon.hedgerow.tools, or the one in KIT_PUSH_RELAY_URL / the push_relay_url setting if you run your own) a push that carries that reference and the app's device handles, nothing else. The relay and Apple therefore never see server names, containers or versions. When the push arrives, the app fetches the text from your own server (GET /api/v1/push/events/{ref}) with its token and shows it. The server registers itself with the relay the first time the channel fires, so it needs outbound HTTPS to the relay. The upgrade to the release that adds the channel creates three empty tables (push_devices, push_events, push_registrations) after the usual copy in backups/; the release before it refuses a database this one has started on, so restore that copy to go back.

Install

Wren is a server (the web UI, once) plus a small agent on every Docker host it looks after. Start the server:

mkdir wise-wren && cd wise-wren
curl -fsSLO https://raw.githubusercontent.com/Ferdinand99/Wise-Wren/main/docker-compose.yml
docker compose up -d

Open http://<host>:3003/setup to create the first admin. Until the first admin exists, /setup asks for a setup token: set WW_SETUP_TOKEN, or read the one Wren makes up and logs at the first start (docker compose logs wise-wren, a line with /setup?token=…); scripted installs can set WW_SETUP_OPEN=1 instead. Then set the address agents use under Settings → General (or WW_PUBLIC_URL), then Servers → Add server: Wren shows the agent's token once, with the docker run line for that host. On Unraid, install Wise Wren and Wise Wren Agent from Community Applications (templates). Images are on GHCR for amd64 and arm64: ghcr.io/ferdinand99/wise-wren and ghcr.io/ferdinand99/wise-wren-agent, :<version> or :latest.

The agent has the Docker socket, which is root on its host. Read the guides before the first update:

Planned for v1

Updates Around them
Containers, Unraid templates, Compose stacks, script stacks Docker Hub, GHCR, Quay and any OCI registry; GitHub releases
Notify, approve or automatic, per server and per target Release notes with each update, when Wren can find them
Scheduled updates and automatic windows with exclusions Vigilant Vole maintenance windows and monitor-based health checks
Snapshot before, health check after, automatic rollback Notifications to ~40 channels
A history of every run, step by step REST API and MCP tools for everything the web UI can do

Most of the table is in the early releases; static binaries, a Linux installer and wider testing on other Linux hosts come before v1.0. Not in v1: the iOS app (planned later), updating Unraid OS, plugins, VMs, LXC or Kubernetes, building images from source, and offsite backups (Wren's snapshots are short-lived rollback points, not backups). See docs/design.md for the full scope and the phases.

Wren is part of Hedgerow, a family of small self-hosted apps, with Vigilant Vole, Nimble Newt and Keen Kestrel. Like its siblings, it is one Rust binary with SQLite in the family's design, plus a small agent for each server.

Support

Hedgerow is built in spare time and is free to use. If you find it useful, you can support it through GitHub Sponsors or Ko-fi. Thank you.

License

GNU AGPL-3.0-only

The licence texts of the Rust crates inside the images are in THIRD-PARTY-NOTICES (server) and agent/THIRD-PARTY-NOTICES (agent). Each image carries its file, with the AGPL text, in /usr/share/doc/wise-wren/ and /usr/share/doc/wise-wren-agent/. scripts/notices.sh makes the files (cargo-about, pinned), and CI fails when one is out of date or when a dependency has a licence that is not on the allowlist in about.toml. After changing a dependency, run scripts/notices.sh and commit the result.

About

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages