Skip to content
SHC Docs

Flow: app uninstall

Layer 11. Lifecycle. Lifecycle

Step-by-step trace of shc uninstall <deployment>. The CLI sends the request to shcd and refuses with X503738DMNREQ when it cannot reach the daemon. Source of truth is the ce modules/app package: router.go’s startAsyncUninstall (the shared chokepoint behind both POST shc.stack.uninstall and DELETE /api/resource/Stack), service.go’s Service.Uninstall (the state half), and install_runner.go’s ExecuteComposeDown (the teardown half, reached through RunUninstallWithObserver). For multi-deployment teardown during clone/move see uninstallPhase in modules/clone/service.go, summarized at the end.

Uninstall is not transactional. Unlike install (which rolls back on failure) and update (which reverts from a snapshot), the teardown phase is a best-effort forward pass: most steps are individually guarded, and a failure is logged but does not block later steps; “user said delete this” should make progress even when parts of the system are already broken. The exceptions are deliberate and sit at the edges: the gates in Phase 0 refuse before anything is mutated, and a managed-DNS release failure at the very end fails the operation loud (X500979DNSRMV) instead of silently stranding records.


Phase 0: synchronous gates (nothing mutated on refusal)

Section titled “Phase 0: synchronous gates (nothing mutated on refusal)”
  1. Protected-deployment destroy guard. GetProtected on the resolved (tenant, stack, environment); a protected deployment refuses with X409001DEPROT before the backup gate, the state-row drop, and the async teardown. Unprotect first (shc unprotect).
  2. Vdeployment discrimination. A name carrying the <stack>/<instance> grammar is a vdeployment: it has no top-level deployment row, so it skips the deployment phases below and instead takes an uninstall claim (GateVdeploymentUninstall, removing + this operation’s id) so an install racing underneath refuses symmetrically. Its teardown is UninstallVdeployment, dispatched inside ExecuteComposeDown.
  3. Pre-uninstall backup gate. The deployment row is read first (requireUninstallRow, same resolved coordinate): no row answers X404906STKNOF naming the tenant and environment searched, and a store that cannot be read answers its own error, so a deployment that was never there is not reported as a failed backup. Only a row that was found reaches GateUninstallBackup, which backs the deployment up BEFORE any mutation; a backup failure aborts the whole uninstall here. The backup is a no-op when --no-backup, no hook wired, or no repo configured; the row check runs either way.

Phase 1: synchronous state drop (Service.Uninstall)

Section titled “Phase 1: synchronous state drop (Service.Uninstall)”
  1. Lookup ⇒ X404906STKNOF if absent.

  2. pre_uninstall / post_uninstall hooks (state-level runHook; best-effort, a failure never aborts). Status is set to removing between them for any observer polling.

  3. Deployment row delete: the single deletion point. Dependent rows are NOT deleted by code: the ent schema (ent/schema/deployment.go) declares the FK actions on the deployment’s edges, and the database does the rest when the row goes:

    Dependent tableFK action
    service (and its container rows, via the service edge)ON DELETE CASCADE
    host_mapping, port_mappingON DELETE CASCADE
    integration (as consumer AND as provider)ON DELETE CASCADE
    deployment_node (the occupancy set)ON DELETE CASCADE
    vdeployment (instances this deployment hosts)ON DELETE CASCADE
    child deployment rows (tombstone self-ref)ON DELETE CASCADE
    backupON DELETE SET NULL; backup rows outlive the deployment
    scheduleno FK at all, purged by code in Phase 2

    The in-memory repo (unit tests, non-durable mode) is not joined to the state map, so Service.Uninstall sweeps its integration rows explicitly, a mirror of the cascade, not a second mechanism.

  4. Quota release (recordQuotaDelete): drops the usage counters this deployment reserved on install.

  5. In-memory forget (forgetStack): evicts the health snapshot shc status reads; it is not DB-backed and has no other eviction path.

Phase 2: async teardown (ExecuteComposeDown, streamed over the operation’s SSE)

Section titled “Phase 2: async teardown (ExecuteComposeDown, streamed over the operation’s SSE)”
  1. Protected guard again, at the destroyer. RefuseIfProtected re-checks off the manifest sidecar; a guard sited only at the callers covers only the callers someone remembered. With --data, RefuseIfAnyVdeploymentProtected also refuses if any hosted instance is individually protected (their sidecars live inside this deployment dir).
  2. Manifest read. The persisted manifest.json supplies project name, runtime, hosts, integrations. Present-but-unreadable refuses (X500969DEPSTU) rather than destroying on a guess; missing means never-recorded, and the teardown proceeds best-effort against the conventional project name.
  3. pre_uninstall app hook jobs: while the containers are still up, so service-context jobs (drains, deregistrations) have a live target. Best-effort.
  4. Edge teardown. Every -i edge’s authored jobs.unintegration runs: the consumer plug’s unwire, then the provider socket’s revoke. Best-effort; it cannot fail the uninstall.
  5. Runtime teardown stops the deployment’s replica projects and runs ComposeDown for its runtime. Volumes are removed only with --data. Then a label-matched sweep (pruneOrphanComposeResources) catches stray networks (and, with --data, volumes).
  6. Credential + role reaping. revokeConnectionEdges revokes connection-minted sub-credentials this deployment owns (ownership-guarded; KeepCredentials skips it; ce modules/app/install_runner.go), and the deployment’s stack:<name> Keycloak access role is reaped. Best-effort, loud on failure.
  7. Ingress route file removal (RemoveIngressRouteFile): local best-effort; the Traefik-host reconcile’s orphan sweep is the real cross-node cleanup.
  8. post_uninstall app hook jobs: after the containers are down but BEFORE the rendered artifacts are removed (the job definitions still need to exist on disk). Service-context jobs are rejected; http/container jobs run.
  9. Artifact removal. With --data the whole deployment dir goes (os.RemoveAll). Without it, removeRenderedArtifacts keeps mounts/ (the data) and vdeployments/ (per-instance state incl. protection mirrors) and removes everything else; a real teardown that a later reinstall of the same identity picks back up.
  10. Managed-DNS release. RetireDeploymentDNS latches first (so the cluster reconcile cannot re-register records off the sidecar mid-teardown), then DeleteDeploymentDNSRecords removes every record the deployment self-registered. The ONLY skip is KeepDNS (a same-key relocation; ce daemon/services_seams_stack.go). A failure here surfaces at the end of the teardown as X500979DNSRMV, the one loud tail.
  11. Schedule purge. SyncDeploymentCrons with an empty crons map removes every source == "app" schedule row for the (tenant, stack, environment) tuple, leaving operator-created (user) rows alone. Schedule rows carry no deployment FK, so no cascade covers them; this in-process purge is the mechanism.
  12. Lifecycle-config purge (PurgeDeploymentLifecycleConfig): drops lease.expires_at / deployment.protected config so a reinstall of the same identity cannot inherit a dead deployment’s expired lease.
  13. Row purge tail (PurgeStackRow): an idempotent re-delete of the deployment row plus a re-broadcast. The Phase-0 backup’s quiesce fallback may restart the deployment, and that restart’s re-register can land AFTER Phase 1 dropped the row; this sweeps the resurrected phantom regardless of which backup path ran.

Teardown of several deployments (clone, tenant teardown) is driven by the clone module: uninstallPhase in modules/clone/service.go asks ComputeUninstallOrder (consumers come down before the providers they depend on) and uninstalls one deployment per member. Two per-member preconditions are spent immediately before each destructive call: the verify phase must have OBSERVED that member’s target serving (refuseUnlessTargetProven, X500629CLNDST) and the target must hold that member’s bytes (refuseUnlessDataProven); a teardown reached by any path that did not prove both refuses instead of proceeding.

StepEventMeaning
Uninstall successA200101STKUNIDeployment uninstalled
Protected refusalX409001DEPROTDeployment is protected
Manifest unreadableX500969DEPSTURefuse rather than guess
DNS-release failure (loud tail)X500979DNSRMVRecords may be stranded
Ordered: per-deployment progress / failure / summaryA200401STKUNO / A400401STKUOF / A200402STKUOCdeclared in modules/app/events.go
InstallUpdateUninstall
Failure strategyRollback (reverse-order cleanup)Revert (restore snapshot)Gate first, then best-effort forward
What happens on mid-flight failureStack rolled back, user sees original errorStack reverted to pre-update stateLogs accumulate; teardown proceeds (only the DNS tail fails loud)
What can leave zombiesNothing (unless --no-rollback)Nothing (revert itself can fail → failed)External DNS (loud), external vault secrets, hook side-effects