In-built self-update: archied update replaces the update scripts #1648
Notifications
Due Date
No due date set.
Depends on
#492 Automatic updates, off by default
sam/archie
Reference: sam/archie#1648
Reference in new issue
Block a user
Updates run in Go inside the existing binaries instead of the bash scripts archie-update-check, archie-update-install and archie-update-watchdog. Done when the scripts and the code that runs commands and parses ARCHIE_UPDATE_RESULT are deleted, and Install on Settings > Status, chat /update and automatic installs all call one Go path. The --from-source build mode is dropped.
Imported from beads
archie-core-wmvy· GitHub #1528 · type epic · priority P1 · created 2026-10-06archie's PRD is ready -- awaiting your go/no-go.
PRD: in-built self-update (#1648)
Recommendation: green-light the small parts, and settle one decision first. Three of the epic's four done-criteria already hold in this tree. What remains is (a) deleting the subprocess between
releaseupdateand the daemon's host transaction, (b) dropping--from-source, and (c) the chat/updateinstall, which is new behaviour rather than consolidation. (b) and (c) are cheap. (a) is the whole PRD, because it forces a choice of where the daemon's host wiring lives. My recommendation is a newDaemonService.InstallReleasestreaming RPC.1. Restating the epic against the tree
Verified on
feat/1648-…at 1.61.3, empty[Unreleased]:scripts/directory.archie-update-check|install|watchdogappears only inCHANGELOG.md:296,1225anddocs/news/releases.json— history, which is not rewritten. Nothing inTaskfile.yml,.woodpecker/,install.shorinternal/releaseupdatereferences them.archied update check|install|watchdog|agent-image(internal/app/archied/update.go:39-57); transaction, journal, watchdog, DB backup/restore, topology plan and rollback ininternal/releaseupdate(20 files);releaseupdate.WatchdogBinary = "archied"(transaction.go:39) — the watchdog is a frozen copy of the daemon./api/chat/update/install(ui/src/lib/api.ts:349→internal/webui/chat.go:598-641); the release canary posts to the same endpoint (releaseupdate/canary_dashboard.go:259, driven by.woodpecker/canary.yaml→archied release canary check -dashboard); both end inreleaseupdate.Service.Install(service.go:207). There is no other automatic install path in the tree — no scheduler and no alert-driven install (alerts only check:internal/app/archied/alerts.go:275).ARCHIE_UPDATE_RESULTArchiedInstallerexecs the sibling archied (installer.go:60-70), scans stdout forResultSentinel(installer.go:79-84, const at:21), andrunUpdateInstallprints that line (update.go:148).--from-sourceinstall.sh:35,53,73,171,190;README.md:119.So the epic's wording hides the work: the only real technical item is the subprocess, and the only real product item is chat
/update.2. The decision this PRD exists to settle
Service.Installreaches the host transaction by spawning the daemon because the wiring is unexported inpackage archied:hostTransaction(update.go:196),systemdUnits/dockerImages/stateDatabase/daemonHealth(update_host.go, ~113 lines, which importsinternal/app/statestore),imagePolicy(update_image.go, ~78 lines),spawnWatchdog(update.go:207-238).cmd → app → {domain, infrastructure}and dragsinternal/app/statestoreacross an app boundary.internal/infrastructurepackage. Not just a move:stateDatabasecomposesstatestore.RunRecovery, whose own doc comment says it depends onopenStateStoreControlPlane— the state store's app root (internal/app/statestore/recovery.go:11-16). Onlycmd/archie-state-storeandinternal/app/archiedimport that package today. Moving the wiring as-is makes two more binaries import another service's app package, so (b) also means relocating or splitting the state store's recovery code — larger than the 250 lines it looks like.proto/daemon/v1/daemon.protohas onlyCheckRepository. Rule-consistent ("services own contracts", "a new binary exists only for a new service or a real process boundary"), and the client side already exists: the UI dials the daemon's listener forCheckRepository(internal/app/archieui/run.go:146,internal/infrastructure/daemonrpc/client.go:31). Cost: proto + generated code + a streaming progress channel.AGENTS.mdsays a new mechanism gets stopped and assessed — this is that assessment.-result FILE; the child writes theResultJSON there and the parent reads it aftercmd.Wait(). ~20 lines changed, no new mechanism — but it does not meet the epic's "delete the code that runs commands".Recommendation: (c). It deletes the hop rather than relocating it, keeps the daemon the single owner of the host transaction (it is the only binary that ever ran
systemdUnits,dockerHealth, the DB backup and the image policy), and removes the odd shape where the caller computes the distribution source and passes it to a child via flags.Two facts found while checking make (c) cheaper than it looks, and one risk it does not remove:
Transaction.Preparetakes the state lock non-waiting and returnsErrInstallInProgress(prepare.go:66-75), and refuses if a journal exists. No new daemon-side guard is needed; the webui's ownupdateInProgressmutex (chat.go:618) stays as a UX gate.controlplanerpc.UpdateService(reader, "").Catalogatalerts.go:275overb.controlPlaneRPC. So the RPC request carries the version and the report meta, not-source/-key/-channel.release.jsonorder, soarchiedis stopped first, and an RPC running inside archied could be cut off before it returns.Preparefinishes beforespawnWatchdogis called, so the window is small, and the harness listener already drains in-flight RPCs with a 10s cappedGracefulStop(harness.go:227-231). The handler must return immediately after spawning, and the web-ui handler must treat a dropped stream after the request was sent as "install started, outcome arrives via the phase-2 report" — the same rule the canary already applies (canary_dashboard.go:243-249). This must be exercised on a real systemd host before the change is called done; I have not run it.archied update install, documented indeployments/systemd-user-service.md:38anddeployments/INSTRUCTIONS.md:81), so that host still has a path.3. Proposed solution
3.1 Daemon contract. In
proto/daemon/v1/daemon.proto:Progress lines are the
Transaction.Progresscallback (update.go:207already routes it to stdout).3.2 One Go path, in archied. Extract the body of
runUpdateInstallintoinstallRelease(ctx, configPath, binDir, version, source, meta, progress) (releaseupdate.Result, error)doinghostTransaction→Prepare→spawnWatchdog. Two callers:archied update install(unchanged flags, unchanged operator use), which prints the result as human lines instead of theARCHIE_UPDATE_RESULTsentinel;repositoryServer(or a siblinginstallServer) that streams progress then the result, reads update-settings from the control plane for the source, and returnsResultmapped intoInstallReleaseResult.Authorization follows the existing
CheckRepositorypattern (repository_check.go:31-48): require a signed-in principal andAccess.Authorize(principal, access.ActionUpdate, …), becauserpcidentity.Callersdoes no method-level gating and the install runs with the daemon's credentials. The dashboard already requires the same action at/api/chat/update/install(internal/webui/authorize.go:412), so this is a re-check, not a new policy.3.3 Client and deletion. Replace
ArchiedInstallerwith aDaemonInstallerininternal/releaseupdateimplementingInstallerandInstallable: stream events, forward progress, build theResult. DeleteArchiedInstaller,ResultSentineland the exec/scanner entirely.ErrNotConfigured(declared ininstaller.go:25, referenced byinternal/webui/chat.go:533) moves toservice.goor goes away with its one caller. Wire it ininternal/infrastructure/controlplanerpc/vocabulary.go:132-145, where UI (archieui/run.go:92) and gateway (archiegateway/chat_setup.go:105) both build theirreleaseupdate.Service.CanInstallbecomes "a daemon target is configured": today it probes for an executable beside the caller (installer.go:34-44), and with no cheap RPC to probe there is no honest second answer. A stale or unreachable daemon then surfaces as an install error, which the dashboard already renders (VersionsCard.vue:150-155).3.4 Chat
/updateinstall — recommend splitting out./updateonly reports today (gateway.go:365-389→handleUpdateCheck), andgateway.UpdateServicedeclaresDeferandInstallthat nothing calls (gateway.go:83-84; the onlyUpdates.Install/Updates.Defercall sites areinternal/webui/chat.go:587,633on webui's own interface). So the epic's "chat /update … call one Go path" is new behaviour: a command to trigger an install from chat, plus the gateway dialling the daemon (it does not today —internal/app/archiegatewayhas no daemon client). Authorization is already settled:/updateis admin-only (internal/gateway/slash_access.go:50). Two sub-items belong here regardless: delete the two dead interface methods, and file the chat-triggered install as its own issue with its own confirmation UX. If the maintainer wants it in this change, it is +~40 lines (path args, a confirm step, gateway daemon dial) on top of the above.3.5 Drop
--from-source. Remove the flag, its usage lines, thegit clone+go buildblock and thegit go jqprerequisite branch frominstall.sh; rewrite the x86_64 error at:174(it currently tells the user to "use --from-source") to say what is actually supported; drop the sentence atREADME.md:119. Say the consequence out loud in the changelog: releases are linux-amd64 only (prepare.go:113refuses otherGOOS/GOARCH,release.jsonnames linux-amd64), so a non-x86_64 host hastask buildand an operator runningarchied update installby hand, and nothing else.README.md:102already requires x86_64, so this deletes an escape hatch the product never supported.install.sh:14-15MODULE/SOURCE_GITand theLDFLAGSdev-stamp line go with it.3.6 Docs.
deployments/INSTRUCTIONS.md:81-100documents the subprocess form ("runsarchied update install -version X", "hands the transaction toarchied update watchdog") and must describe the dashboard asking the daemon, with the watchdog step unchanged.deployments/systemd-user-service.md:38,177describe the CLI path and stay valid. CHANGELOG entry under[Unreleased], sequenced as a change to the install path and the installer flag, not a fix.4. Files and components affected
proto/daemon/v1/daemon.proto;internal/contracts/daemon/v1/*(regenerated, committed —task proto:generate)internal/app/archied/update.go(extractinstallRelease, drop the sentinel print), newupdate_install_rpc.go(handler),internal/app/archied/harness.go:214(register)internal/infrastructure/daemonrpc/client.go(streaming client)internal/releaseupdate/installer.go(deleted) →internal/releaseupdate/daemon_installer.go;service.go(ErrNotConfigured, if it survives)internal/infrastructure/controlplanerpc/vocabulary.go:128-147internal/app/archieui/run.go:92,internal/app/archiegateway/chat_setup.go:105(installer argument; gateway only if chat install is in scope)internal/gateway/gateway.go:81-85(delete dead methods)internal/webui/chat.go:598-641(dropped-stream handling; progress/result shape unchanged —VersionsCard.vue:143-150readsprogress[]andresult.installed)install.sh,README.md:119,deployments/INSTRUCTIONS.md:79-100,CHANGELOG.mdinternal/releaseupdate/{transaction,prepare,topology,promote,canary,journal}internals andtransaction_test.go,topology_test.go,promote_test.go,canary_test.go,release_test.go. Noinstaller_test.goexists, so nothing is orphaned.5. Acceptance criteria
internal/releaseupdate/installer.gois gone,ResultSentinel/ARCHIE_UPDATE_RESULTappear nowhere in the tree, and no package outsideinternal/app/archiedspawnsarchiedto install.result.installedshowsarchiedandarchie-agent, the watchdog restarts the units, and the outcome panel fills from the phase-2 report. Verified by hand on a host, not by unit test.Prepare's lock and the webui mutex).archied update install -version Xfrom a shell still installs, still refuses an unmanaged host's missing unit with the printed migration plan (checkUpdateTopology), and prints the outcome without a sentinel line.archied update install -version Xon a host with a pending journal still says so.ActionUpdate, and the refusal is covered by a test at the seam (security boundary — the one placeAGENTS.mdwants a test).install.sh --from-sourceis rejected as an unknown option;install.shon a non-x86_64 host fails with a message that names the real alternatives; a normal x86_64 install is unchanged.gateway.UpdateServicedeclares onlyCheck(orCheck+ whatever the chat-install issue wires), andgo build ./...proves nothing referenced the removed methods.task checkis green on the tree that ships it, includingtask proto:generateproducing no diff.6. Non-goals
Transaction, the journal, the watchdog, topology migration or rollback. Unchanged.--from-sourceremoval into a supported arm64/other-arch release path. If that is wanted it is its own issue, andprepare.go'sruntime.GOARCH != amd64refusal plus the signed statement's platform field are the real work.task build,deployments/dev.toml) — untouched by--from-source.CHANGELOG.mdpre-1.61 entries anddocs/news/releases.jsonkeep theirarchie-update-*mentions.7. Estimated diff size
Hand-written: ≈ +120 / −150.
installer.go−85;update.gosentinel/marshal −10;gateway.go−3;install.sh−~35;README.md−1.daemon_installer.go~+55;daemonrpcclient ~+25;vocabulary.go±10; docs/changelog ~+10.internal/contracts/daemon/v1/fromtask proto:generate, committed with the change.For comparison: option (b) is ≈ +250/−250 of moved code plus a decision about
internal/app/statestore's recovery code being imported by two more binaries; option (d) is ≈ +20/−40 and leaves the epic's fourth criterion unmet. Chat-triggered/updateinstall, if included, adds ~+40.8. Open questions for the maintainer
/updateinstall in this change or its own issue? Recommended: its own issue. It is the only genuinely new behaviour in the epic, it needs the gateway to dial the daemon, and it needs a confirmation step before an install runs from chat.Nothing in this PRD was executed against a live systemd host; the two things that need a real host to confirm are the RPC response surviving the watchdog's stop and the progress stream reaching the dashboard across the restart.
Decide in chat or on the dashboard.