mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-09-01 13:18:08 +00:00
Anso
275c654407
* feat(fleet): add self dev-build detection primitives Split compareLocalToRemoteTag into compareLocalToRemoteTagDetailed (returns the probe's primary digest alongside the match/update/error verdict) with compareLocalToRemoteTag now a thin wrapper, so a caller that needs both the verdict and the digest no longer has to probe the same mutable tag twice. Add detectSelfDevBuildUpdate, which compares the running container's own image against the rolling ghcr.io/studio-saelix/sencho-dev:dev tag using the new detailed comparison, laying the groundwork for surfacing dev-build updates in Fleet. * feat: add isSenchoDevRepository and isSenchoDevFloatingTag predicates Add two pure predicate functions to helpers/selfUpdateCompose.ts for identifying Sencho dev repository references and floating tag variants: - isSenchoDevRepository: checks if a reference is to the ghcr.io/studio-saelix/sencho-dev repository, including digest-pinned and dev-<sha> tag variants - isSenchoDevFloatingTag: checks if a reference is specifically the floating :dev tag on the Sencho dev repository (not digest-pinned, not immutable dev-<sha>) Both functions reuse existing parsing patterns (normalizeImageRepository for repository extraction, classifyImagePin idiom for digest and tag detection) to maintain consistency. Add comprehensive test coverage in self-update-compose.test.ts covering all specified test cases including edge cases (malformed refs, unrelated repos, digest pins, etc.). * feat(gitops): wire dev-build detection into MonitorService Adds a dev_build_update_available notification category and a new checkSenchoDevBuild() cycle in MonitorService that detects when the running container has fallen behind the rolling ghcr.io/studio-saelix/sencho-dev:dev build it is pinned to, using detectSelfDevBuildUpdate() and isSenchoDevFloatingTag(). Availability state is written unconditionally so the Fleet update affordance never depends on notification delivery succeeding, while a separate dedup key prevents re-notifying for a digest already announced. Also guards checkSenchoVersion() so a dev-repo pin no longer produces a false positive stable-release update notification. * feat(fleet): surface dev-image status and build availability Fleet's GET /update-status now reports isDevImage (any reference to the sencho-dev repository, including digest pins) and devBuildUpdateAvailable (the exact floating :dev tag with a newer build observed, read from the system-state key MonitorService already maintains). A dev-pinned local node forces updateAvailable to false and clears any stale stable-release skip, since that skip was computed before image-pin classification and would otherwise leak a bogus "Skipped" state onto a dev row. Made MonitorService's SENCHO_DEV_BUILD_AVAILABLE_KEY constant public so both call sites share one string instead of duplicating it. * fix(fleet): omit targetVersion for a dev-image update trigger updateRequestInit() always forwarded latestVersion (the latest stable release) as targetVersion whenever it was valid semver, even for a dev-pinned node. The backend already ignores targetVersion safely for a floating pin, so this never caused an actual repin, but it produced a misleading "Update to X.Y.Z" button label and confirm-dialog copy for an update that installs the dev image, not that stable release. * feat(fleet): add integration-image badge and dev build update button NodeCard now shows a persistent "Integration image" badge whenever a node's compose image is any sencho-dev reference, independent of update availability, visible to every role. When a newer dev build is available, a solid brand-colored "Update dev build" button appears alongside it, admin-only, reusing the existing update trigger and requireAdmin route. Styled distinctly from the neutral stable "Update to X.Y.Z" button so an operator always knows which channel they're acting on. * feat(fleet): add dev-image copy to the local update confirm dialog LocalUpdateConfirmDialog now recognizes isDevImage and shows a distinct LOCAL - DEV UPDATE kicker plus copy stating the sencho-dev:dev reference will be pulled without rewriting the compose image, and that integration images are unsigned and carry no release attestations. Without this, a dev-pinned node's update confirmation fell through to the generic "Pulls Sencho the latest release" copy. FleetView.tsx threads isDevImage from the node's update status through to the dialog, same source as its other pin fields. * feat(fleet): separate dev and stable availability in the Node Updates sheet The sheet counted stable and dev availability together via the same updateAvailable field, so a dev-pinned node with a build available fell into neither the summary counts nor any row action, and would have misleadingly rendered as "Up to date" once devBuildUpdateAvailable existed. stableAvailable and devAvailable are now tracked separately: the changelog dot lights only from stableAvailable (a dev build has no release changelog), the summary and meta text report the combined total, a dev row shows "Integration build" instead of a stable version in the Latest column, and the existing Update button/badge now also fires for devBuildUpdateAvailable. Update all and Skip stay stable-only, since both already gate on fields a dev row never satisfies. * feat(fleet): bring dev-build detection and update to Mobile Fleet Mobile Fleet previously had no update capability at all: it only polled /fleet/overview and never called useFleetUpdateStatus, so it could not show the stable update flow either. It now fetches update status alongside the overview poll, shows the same "integration" marker as desktop on any dev-pinned node's card (visible to every role), and gives admins a dev-build update action. The action renders as a sibling of the card's own button rather than nested inside it, since the card is itself a <button> and a nested button is invalid HTML with broken touch semantics. It reuses the exact same triggerNodeUpdate/confirmLocalUpdate flow and LocalUpdateConfirmDialog /ReconnectingOverlay components desktop already renders, so there is no parallel API implementation to keep in sync. * feat(notifications): wire dev_build_update_available through the frontend Adds the category to the frontend NotificationCategory union, its bell label, the per-node "mute update notifications" bundle, and the bell's friendly dot-color memo. The changelog navigation and "View changelog" button stay scoped to node_update_available only: a dev build has no release changelog entry to navigate to. * docs: document dev-build detection and update on Fleet Adds the dev_build_update_available notification category, the persistent Integration image marker, and the dev-build update action (desktop and mobile) to the alerts-notifications, verifying-images, fleet-view, remote-updates, and upgrade pages. States the detection cadence explicitly: it polls on a fixed interval and reflects the newest build observed, not necessarily every individual build. * fix(gitops): sanitize the inconclusive-reason debug log for log injection CodeQL flagged the dev-build check's debug log as depending on a user-influenced value (a registry probe failure reason can trace back to external input). Wraps it with sanitizeForLog(), the existing repo-wide remediation for this class of finding, matching how registry-api.ts already handles the same pattern. * test(gitops): cover the no-repin invariant on a dev-build self-update Proves triggerUpdate(), called with neither targetVersion nor targetImageRef (the exact dev-build update call), pulls the current compose-declared ref unchanged and never stages a compose rewrite. * fix(fleet): use the shared busy-button pattern on Mobile Fleet's dev update action Replaces the local Loader2 plus boolean pending logic with BusyButton so busy behavior and interaction locking stay in sync with the rest of the app's async click surfaces. * test(gitops): exercise the production call shape in the no-repin regression Fleet substitutes the stable compare target when the request body omits one, so SelfUpdateService receives a targetVersion even for a dev-build update. The guard that protects a :dev install is therefore the semver check inside the repin branch, not the absence of a target. Drives triggerUpdate with a forwarded target against a floating :dev pin and asserts the reference is pulled unchanged with no staged patch, and pairs it with a semver case so the negative assertions cannot pass vacuously.
102 lines
5.1 KiB
Plaintext
102 lines
5.1 KiB
Plaintext
---
|
|
title: Upgrading Sencho
|
|
description: How to update Sencho, what happens during upgrades, and the version policy.
|
|
---
|
|
|
|
<Note>
|
|
Sencho is used in production for day-to-day Docker Compose and fleet management. As a pre-1.0 project it still evolves quickly, so review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and validate against your own setup before deploying it on critical infrastructure.
|
|
</Note>
|
|
|
|
## Upgrade steps
|
|
|
|
Upgrading Sencho is a two-command process. Pull the latest image and recreate the container:
|
|
|
|
```bash
|
|
docker compose pull
|
|
docker compose up -d
|
|
```
|
|
|
|
Or if you're running with `docker run`:
|
|
|
|
```bash
|
|
docker pull saelix/sencho:latest
|
|
docker stop sencho && docker rm sencho
|
|
# Re-run your original docker run command
|
|
```
|
|
|
|
<Tip>
|
|
Sencho is also mirrored on GitHub Container Registry at `ghcr.io/studio-saelix/sencho:latest` with the same tags and digests as Docker Hub. Pull from whichever registry your environment prefers.
|
|
</Tip>
|
|
|
|
Sencho applies any necessary database migrations automatically on startup. No manual steps are required.
|
|
|
|
<Note>
|
|
Remote nodes can be updated directly from the Fleet View without dropping to a shell. See [Remote Updates](/features/remote-updates) for details. Admiral **Hardened Build** installs use a different, entitlement-gated update path instead of the manual steps above; see [Updating the local (gateway) node](/features/remote-updates#updating-the-local-gateway-node) for that flow.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Automatic migrations
|
|
|
|
Sencho handles all schema changes internally. When the application starts, it checks whether the database needs updating and applies any pending migrations automatically. This covers:
|
|
|
|
- **New tables and columns** for features introduced in newer versions
|
|
- **Config import** from an on-disk JSON config file, if one exists from a manual setup
|
|
- **Admin account consolidation** into the multi-user system
|
|
- **Encryption of node API tokens** stored in plaintext (registry credentials are always stored encrypted, so they need no migration)
|
|
- **SSO and RBAC setup** for single sign-on provider config and role-based access
|
|
- **Obsolete column cleanup**, removing unused SSH/TLS configuration columns no longer read or written by the current schema
|
|
- **Blueprint rollout approval** columns (`approval_status`, intent fingerprint, and blast JSON). Existing Blueprints start **pending**. Automatic reconciliation and enforcement pause until an admin opens **Apply now**, reviews the rollout preview, and confirms. New installs behave the same way for each Blueprint until the first confirmation.
|
|
|
|
You never need to run SQL commands, migration scripts, or any manual database operations.
|
|
|
|
---
|
|
|
|
## Backup before upgrading
|
|
|
|
Always back up your data directory before upgrading. If something goes wrong, restoring from backup is the only recovery path. Sencho does not support downgrading or rolling back database migrations.
|
|
|
|
```bash
|
|
# Copy both the database and the encryption key
|
|
cp /path/to/sencho-data/sencho.db /path/to/backup/sencho-pre-upgrade.db
|
|
cp /path/to/sencho-data/encryption.key /path/to/backup/encryption-pre-upgrade.key
|
|
```
|
|
|
|
See the [Backup & Restore guide](/operations/backup) for full backup procedures.
|
|
|
|
---
|
|
|
|
## Pinning a specific version
|
|
|
|
If you prefer to control exactly which version you run, pin the image tag in your `docker-compose.yml`:
|
|
|
|
```yaml
|
|
image: saelix/sencho:0.96.0
|
|
```
|
|
|
|
Fleet can update semver pins directly from the [Node updates](/features/remote-updates) sheet: it rewrites the tag to the selected release before recreating the container. Digest pins and compose values that use variable interpolation must be changed manually before Fleet can update the node.
|
|
|
|
Check [GitHub Releases](https://github.com/studio-saelix/sencho/releases) for available versions and changelogs.
|
|
|
|
<Note>
|
|
Pinning to the `sencho-dev:dev` integration image instead of a release tag is a separate, unsigned track meant for pre-release testing, not this upgrade flow. See [Verifying images · Integration tag](/operations/verifying-images#integration-tag-post-merge-pre-release) and [Remote Updates · Updating the local (gateway) node](/features/remote-updates#updating-the-local-gateway-node) for how detection and the in-app update action work there, and how it differs from **Reapply configuration** (which recreates from the current Compose project without pulling a new image at all).
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Version policy
|
|
|
|
Sencho follows [Semantic Versioning](https://semver.org/) (`MAJOR.MINOR.PATCH`):
|
|
|
|
| Change type | Version bump | Example |
|
|
|-------------|-------------|---------|
|
|
| Bug fixes, performance improvements | Patch | 0.38.0 → 0.38.1 |
|
|
| New features | Minor | 0.38.x → 0.39.0 |
|
|
| Breaking changes | Major | 0.x.y → 1.0.0 |
|
|
|
|
<Note>
|
|
While the version is below 1.0, minor releases (0.x.0) may occasionally include breaking changes. These are always documented in the release notes. Once Sencho reaches 1.0, breaking changes will only occur in major releases.
|
|
</Note>
|
|
|
|
Breaking changes are marked with `BREAKING CHANGE` in the [release notes](https://github.com/studio-saelix/sencho/releases). Subscribe to the repository's releases to be notified of new versions.
|