Fail-closed container image updates for Portainer, Docker Compose, and Podman Compose.
Ripen watches image registries and waits for a new digest to mature before it can update a service. You choose which stacks may update automatically. Ripen verifies service health after each update and rolls back if verification fails. Git-backed stacks receive a pull request for human review.
Quick start · Run continuously · How it works · Safety limits · Documentation
Warning
Ripen recreates containers. Start in monitor mode, review what it records, and
only then decide whether any stack should carry auto_apply: true.
Download a binary from Releases (see release verification), or install with Go:
go install github.com/frankieramirez/ripen/cmd/ripen@latestWith Nix, run nix run github:frankieramirez/ripen -- version.
For the container image, see Run in a container.
For a local Compose stack, run Ripen where the Docker or Podman Compose CLI can reach your engine. The Compose file and its directory must be writable. Read the Compose setup guide for engine requirements and rootless connections. Ripen refuses the privileged Docker socket.
Save this as policy.yaml, adapting the stack path, service name, and health URL
to your deployment:
mode: monitor
state_file: ./ripen.db
stacks:
media:
enabled: true
backend: docker-compose
file: /srv/media/compose.yaml
expected_services: [jellyfin]
health:
target: http://127.0.0.1:8096/healthFor Portainer, follow the Portainer setup guide to configure its API credentials and TLS trust. The example policy shows both backends; Configuration documents every field.
ripen run --mode monitor --config policy.yamlThe first run records the running digest as the Baseline. Later runs report a
Candidate when the registry moves. A Candidate matures after
candidate_min_age_seconds (one day by default) and a second observation.
Monitor mode leaves your services unchanged.
| Command | What it shows |
|---|---|
ripen status --config policy.yaml --pretty |
Configured services and their current state |
ripen candidates --config policy.yaml --pretty |
Candidates and whether they have matured |
ripen explain media --config policy.yaml --pretty |
Why Ripen would or would not act on the stack |
ripen audit --config policy.yaml --pretty |
Recorded actions |
Omit --pretty for the JSON Response envelope used by scripts and agents. Ripen
never infers this flag from a TTY. See Agents for the response
format and exit codes.
ripen daemon --config policy.yamlThe daemon observes at startup and on fixed
check_interval_seconds ticks, checking up to two stacks concurrently. Set
observation_concurrency from 1 through 8 to change that limit. While one stack
deploys, verifies, or rolls back, unrelated stacks continue receiving checks.
The active stack waits until a later scheduled check. Missed checks coalesce
instead of accumulating a backlog.
Deployments remain sequential, with at most one update per Apply cycle and a full interval after Apply completes before another cycle may update. An open Circuit breaker permits observation but blocks updates and Proposals until a person clears it. The daemon writes its Event stream to stderr.
status reads stored state; a successful response does not prove that the daemon
is making progress. Its scheduler, stack checks, and service evaluations show
stored progress separately from Candidate age; an unfinished Transaction shows
its phase and whether its ownership has expired. Check the run.finished Events
in the container log. The
Notifier is off unless configured; use ripen notify test to verify delivery.
If status shows an interrupted Transaction, ordinary breaker clearing refuses
to resume deployments. Once you have confirmed the earlier backend request
finished and restored a healthy Baseline, use clear-breaker --reconcile --reason "...". See recovery requirements,
including the restriction on interrupted Proposal requests.
The published image includes Ripen and CA certificates. Use it with a Portainer policy; local Compose backends also need an engine CLI, which this image does not include.
Set state_file: /data/ripen.db in your policy. Create a writable ./data
directory for the container's UID/GID 65532:65532, and mount the credential
file at the path configured by portainer.api_key_file:
services:
ripen:
image: ghcr.io/frankieramirez/ripen:latest
command: ["daemon", "--config", "/config/policy.yaml"]
read_only: true
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
volumes:
- ./policy.yaml:/config/policy.yaml:ro
- ./data:/data
- ./portainer-api-key:/run/secrets/portainer-api-key:roEnsure the container user can read the policy and credential file. If you use a
custom CA, mount that file read-only at portainer.tls_ca_file too. Health check
URLs must be reachable from inside the container.
- Observe. Read what is deployed and what is running, and ask the registry what the tag points at now.
- Baseline. The first time, record the running digest only if it can be proven. If an update is already pending, Ripen refuses to guess.
- Ripen. A new digest becomes a Candidate. It must be seen twice and be older than the maturity window before it is eligible for anything.
- Apply, in apply mode, on a stack that opted in: check every configured
service's health first, pin exactly one image to
tag@sha256:…, deploy, and verify every service again. - Roll back if verification fails: restore the Baseline digest and open the Circuit breaker. Further updates and Proposals stay blocked until a person clears it with a reason. Monitor and reads continue.
Git-backed stacks replace step 4 with a Proposal: one deterministic pull request pinning the digest, which Ripen opens and never merges.
| Limit | Behavior |
|---|---|
| Privileged Docker socket | Ripen refuses it at configuration load. |
| Update scope | One service per run, only where you opted in. |
| Proposals | Ripen opens a pull request and leaves merging to a person. |
| Portainer TLS | An explicit CA file or exact certificate fingerprint is required. |
| Agent permissions | MCP has no tools to apply updates or clear the Circuit breaker. |
Roadmap covers non-goals and possible future work.
| Page | What it covers |
|---|---|
| Configuration | Every policy field, and what refusing to start protects |
| Portainer | The API backend, its least-privilege user, and TLS trust |
| Compose | Docker and Podman Compose, drift, and rootless sockets |
| Agents | The CLI and MCP surface, envelopes, exit codes |
| Proposals | Git-backed stacks and the pull-request transaction |
| Notifications | The Event stream, the webhook Notifier, suppression |
| Architecture | How the pieces fit and why they are shaped this way |
| Troubleshooting | What each result code means and what to do about it |
The vocabulary in all of them is defined once in CONTEXT.md.
Ripen holds credentials for the systems that run your services. Read
SECURITY.md before deploying it, and report anything you find
through GitHub's private vulnerability reporting rather than an issue.
Every release archive carries GitHub build provenance. Check the one you downloaded before you extract it:
gh attestation verify ripen_<version>_linux_amd64.tar.gz --repo frankieramirez/ripenThe checksums file is attested the same way.
Open an issue before a pull request. See CONTRIBUTING.md.
This is a project maintained for its author's own use; contributions are
welcome and reviewed on a best-effort basis.
MIT. See LICENSE.