Decommission, remove, or reinstall

“Uninstall” is four separate decisions

Nook deliberately has no single command that silently deletes application data and backups. Decide each boundary explicitly:

1. Stop serving: reversible local shutdown.
2. Revoke commercial authority: prevents new connected credentials/activation according to the entitlement lifecycle.
3. Remove software: remove nookctl, release files, and container images after retention review.
4. Dispose of data: irreversible database, file, backup, configuration, key, and media sanitization under the organization’s approved policy.

Do not combine these just to make the process shorter.

Before decommissioning

• Identify the Customer Portal organization, entitlement, local deployment ID, and local owner.
• Decide whether this is temporary shutdown, host replacement, organization closure, or incident containment.
• Put the instance in a communicated maintenance window and block new user traffic.
• Create and verify a final continuity backup and separate file/configuration backup unless policy requires destruction without retention.
• Record legal hold, retention, export, and employee/offboarding obligations.
• Record integrations, bots, webhooks, mail, DNS, TLS, monitoring, and firewall dependencies.
• Assign the person authorized to approve irreversible sanitization.

Reversible stop

sudo nookctl stop
sudo nookctl status

This stops the Compose services and preserves state, data, releases, configuration, activation, and backups. Use this for planned maintenance or before host-level work.

Restart only if the deployment has not been decommissioned:

sudo nookctl start

Revoke or decommission the entitlement

In the Customer Portal, select the exact organization and entitlement. Revoke/decommission only after checking that another active deployment is not using it. Connected registry and activation authority must stop according to the entitlement contract.

Read the local confirmation value:

sudo nookctl diagnostics

Then record local decommissioning with the exact ID:

sudo nookctl decommission --confirm <deployment-id-from-diagnostics>

The command durably binds the exact deployment, managed Caddy configuration, and current container inventory before each terminal phase. It masks Caddy, changes every bound container to restart no, proves the deployment stopped, and then records decommissionedAt. A SIGKILL, Docker restart, or cold boot replays the pending phase before ordinary start can proceed. Data and backups remain preserved, and a wrong confirmation is rejected before the WAL or serving state changes.

After the deployment is marked decommissioned, remove only the Caddy configuration owned by this deployment with the same exact deployment ID:

sudo nookctl ingress remove --confirm <deployment-id-from-diagnostics>

This stops and disables the managed Caddy service and removes only the marker-bound Nook Caddyfile. It deliberately preserves the Caddy package and certificate storage for a separate shared-host and retention decision. It refuses an unmanaged Caddyfile, a live deployment, or a wrong confirmation. For internal TLS, first remove the exact Nook CA trust profile from every managed client. Record the SHA-256 certificate fingerprint, then either retain or destroy /var/lib/caddy/.local/share/caddy/pki/authorities/local/ under the approved certificate-retention policy. Never delete a broader Caddy or system trust directory by wildcard.

Preserve what policy requires

Keep an inventory rather than an unlabeled disk image:

Item	Minimum evidence
PostgreSQL	Exact dump + continuity manifest, hashes, capture time, deployment ID, revision
Files	Archive/object-store snapshot, capture window, integrity evidence
Configuration	Protected copy, release/version association, owner, expiry
Receipts	Activation/update/recovery/decommission safe evidence
Keys/secrets	Separate custody decision; never bundle with general diagnostics
Audit/legal hold	Retention authority and deletion prohibition where applicable

Test that the retained artifacts can be located and decrypted by an authorized recovery operator. Do not keep raw operation keys or expired one-time credentials.

Remove the package and optional repository

Only after the decommission record and retention decisions are complete:

sudo apt remove nookctl

The current connected installer uses its release-bound local Debian package and does not add an APT source or archive key. It does install two Nook release trust anchors. Inspect their exact paths, then remove those anchors after the package is removed:

sudo stat -- /usr/share/keyrings/nook-release-ed25519.pem \
  /usr/share/keyrings/nook-channel-ed25519.pem
sudo rm -- /usr/share/keyrings/nook-release-ed25519.pem \
  /usr/share/keyrings/nook-channel-ed25519.pem

If either expected path is absent, record that result rather than substituting a wildcard or a broader keyring directory. If this host was separately enrolled in a future signed Nook repository, first verify the exact files and then remove only those optional entries:

test ! -e /etc/apt/sources.list.d/nook.list || sudo rm /etc/apt/sources.list.d/nook.list
test ! -e /usr/share/keyrings/nook-archive-keyring.asc || sudo rm /usr/share/keyrings/nook-archive-keyring.asc
sudo apt update

Do not remove Caddy, Docker Engine, Docker Compose, containerd, or skopeo as part of this Nook-specific inventory. They may be shared host dependencies; evaluate them separately against the complete host workload inventory. On a dedicated fresh Nook host, that separate review may approve sudo apt remove caddy; separately resolve any retained /var/lib/caddy certificate data before sanitization. Do not run apt autoremove until that review is complete.

Package removal does not prove that application data, Docker volumes, files, backups, images, configuration, or secret material are gone. That separation prevents an accidental package command from destroying customer data.

Remove runtime artifacts safely

Before any deletion, resolve and record exact targets:

sudo docker ps -a --filter name=nook
sudo docker volume ls --filter name=nook
sudo find /opt/nook /var/lib/nook /etc/nook -maxdepth 2 -xdev -print

There is intentionally no copyable “delete everything” block here. Paths and volume names depend on the installed release, and recursive deletion is irreversible. Your approved sanitization procedure must individually cover:

• stopped Nook containers and networks;
• Nook-specific Docker images and explicitly resolved volumes;
• /opt/nook release artifacts;
• /var/lib/nook local state, data references, support bundles, and backups;
• /etc/nook configuration;
• off-host backup copies and secret-manager entries;
• DNS, TLS certificates, monitoring, mail/provider credentials, bot/webhook secrets;
• physical/cloud volume and snapshot sanitization guarantees.

Never delete broad Docker, filesystem, home, media, or backup roots just because they contain Nook. Shared infrastructure may contain unrelated customer workloads.

Host replacement or reinstall

If the goal is a replacement rather than disposal:

1. keep the old deployment stopped and retained;
2. decide whether this is same-identity recovery or a new-identity migration/fork;
3. use continuity restore only for the same deployment identity and canonical origin;
4. use the migration/fork workflow for a new identity or origin;
5. do not let old and new identities serve simultaneously;
6. verify login, messages, files, notifications, voice, integrations, entitlement, and tenant isolation on the replacement;
7. decommission and sanitize the old host only after acceptance.

Re-registering a new Customer Portal organization is not a recovery mechanism. Contact support when commercial ownership must be transferred or recovered.

Final closure evidence

• Customer Portal entitlement is in the intended terminal state.
• Local nookctl decommission confirmation succeeded.
• DNS and external ingress no longer route users to the instance.
• Retained backup/hold inventory is signed off—or approved destruction is evidenced.
• Bot, webhook, provider, mail, monitoring, and TLS authorities are revoked.
• Exact Nook containers, images, volumes, release files, config, installed trust anchors, and off-host copies were handled.
• Caddy, Docker Engine, Docker Compose, containerd, and skopeo were preserved unless a separate shared-dependency review explicitly approved their removal.
• Shared/user data outside the resolved targets was not touched.
• The decommission record names approver, operator, date, reason, and evidence location.