Plan a self-hosted deployment

Decide whether self-hosting is the right product

Choose self-hosting when your organization needs Nook application data to remain on infrastructure it operates. Self-hosting transfers daily operations to you: host security, DNS, TLS, capacity, backups, recovery testing, upgrades, and incident response.

Choose Nook Cloud when you want a ready service and do not have an operator who can own those responsibilities. A Customer Portal self-host organization and a Nook Cloud organization are separate product records; selecting one does not silently create the other.

Supported topology

The supported baseline is one Nook deployment, one runtime organization. That organization may contain multiple workspaces. The Customer Portal organization represents the commercial owner; its Portal members do not automatically become users on the self-hosted server.

The supported topology uses these components. The signed Nook application release runs API, admin, PostgreSQL, and Redis. On a clean dedicated host, nookctl installs and manages Ubuntu’s Caddy package as the public HTTPS ingress. LiveKit remains a separate customer-operated or managed media authority; the Nook installer does not silently deploy or expose it.

Service	Responsibility	Exposure
Nook API	Authentication, messages, files, apps, realtime coordination	Behind your HTTPS reverse proxy
Nook admin	Local owner and workspace administration	Behind your HTTPS reverse proxy
Caddy	TLS, API/WebSocket proxy, admin proxy, optional web redirect	Host ports 80/443 (or explicitly chosen ports)
PostgreSQL 16	Durable application data	Private Docker network only
Redis	Ephemeral coordination and queues	Private Docker network only
LiveKit	Voice and meeting media	Separate public WSS and WebRTC media endpoints

Do not publish PostgreSQL or Redis to the internet. Do not run two active deployments against the same database or copy a deployment without the documented fork/recovery process.

Host requirements

Start with a dedicated Ubuntu Server 24.04 LTS host on x86_64. This is the only currently verified customer baseline. Before changing package sources or installing anything, the connected installer rejects another OS/version or architecture, less than the 8 GiB assigned-memory boundary, less than 40 GiB of operational free space on /, or a system clock that is not NTP-synchronized. The protected installer also needs disk-backed staging. For a clean install where /var/tmp shares the root filesystem, the first Portal command requires 40 GiB plus four times the exact displayed installer-artifact bytes. When /var/tmp is a separate filesystem, / needs 40 GiB and /var/tmp needs the four-times-artifact staging amount. After the exact download is verified, the command checks the remaining space again against twice the verified expanded archive size. Do not treat a fixed provisioned-disk size as the free-space guarantee; Portal displays the artifact-specific first gate before you copy the command. The release publisher also proves that remaining image bytes, the exact release-input snapshot, and the expanded inner release can coexist inside the 40 GiB host contract. A protected prepared resume checks those immutable snapshot and expanded-release bytes on /var/tmp and the actual /opt/nook/releases filesystem before downloading with a replacement one-use grant.

Resource	Baseline	Planning guidance
Memory	8 GiB	Add headroom for larger workspaces, file processing, and concurrent meetings.
Disk	40 GiB operational reserve plus protected staging	Portal shows the artifact-specific first gate; retain additional growth and backup headroom.
CPU	Modern 64-bit CPU	Reserve capacity for PostgreSQL and media coordination; avoid heavily oversold hosts.
Clock	Synchronized UTC-capable clock	Callback signatures, TLS, tokens, and release manifests are time-bound.
Runtime	Docker Engine with Compose v2	Install only through nookctl prerequisites --install or your approved equivalent.

Use a separate disk or storage class for durable data when possible. A VM snapshot is useful for infrastructure recovery but is not a substitute for the Nook continuity dump and manifest.

DNS, TLS, and network

Allocate stable names before activation. A typical deployment needs two service names and may use one optional convenience alias:

app.nook.example.com   Admin and browser entry point
api.nook.example.com   API and realtime origin
www.nook.example.com   Optional redirect to the admin entry point
media.nook.example.com LiveKit media endpoint, when separated

Requirements:

• Public HTTPS endpoints must have certificates trusted by desktop, mobile, and browser clients.
• Public deployments point the API/admin DNS names at the Nook host and allow inbound TCP 80/443 so managed Caddy can obtain and renew certificates. A private-PKI deployment must explicitly trust its CA on every client; certificate checks are never bypassed.
• Managed TLS requires DNS names in both modes. For an internal deployment, create private DNS records and select Internal TLS explicitly. Numeric IP origins are rejected because ordinary browser, desktop, and mobile TLS clients cannot reliably select Caddy’s IP certificate without SNI.
• The configured canonical API origin must not change during an ordinary restore. An origin move is a migration/fork event, not a DNS-only recovery shortcut.
• Preserve Authorization, WebSocket upgrade, forwarded protocol, and client IP headers according to the reverse-proxy runbook. Never log authorization values.
• Expose only the HTTP(S), WebSocket, and LiveKit media ports required by the signed release.
• Restrict SSH to operator networks and require key-based administrator access.

Mail and central notification gateway

Local account and invitation email must have an approved delivery path. Connected deployments also use Nook’s central notification gateway for the delivery classes explicitly documented by the product. This does not authorize importing message history, local members, or file content into the Customer Portal.

Before launch, prove all of the following with test recipients:

• first-owner/account verification;
• local member invitation;
• passwordless or recovery email paths enabled by your configuration;
• delivery failure handling and retry visibility;
• correct sender domain, SPF, DKIM, and DMARC alignment for your chosen provider.

Data, storage, and privacy inventory

Record where each class lives and who can restore it:

Data class	Required protection
PostgreSQL data	Encrypted storage, continuity dump + manifest, off-host retention, restore drill
Uploaded files	Durable file volume/object store, separate backup, malware-scanning policy
Configuration	Root-readable protected backup, reviewed after each release
Runtime secrets	Secret store or root-only files; never in Git, Portal notes, or support bundles
Deployment private keys	Local-only custody, protected backup if the relevant recovery contract permits it
Logs	Retention and access policy that avoids message bodies, tokens, and credentials

Connected operational sharing is opt-in and privacy-minimized. Read the exact disclosure in the Customer Portal before enabling it.

Backup and recovery objectives

Choose explicit targets before launch:

• RPO: maximum acceptable data loss, which determines backup frequency.
• RTO: maximum acceptable downtime, which determines restore automation and operator coverage.
• Retention: how many daily, weekly, and pre-update backups remain available.
• Off-host copy: a failure of the Nook host must not erase every backup.
• Restore floor custody: retain the greatest deployment revision observed outside the backup so an old restore cannot silently serve stale authority.

PostgreSQL and uploaded-file backups are separate and are not an atomic snapshot. Document how your organization coordinates them and what data window is acceptable.

Commercial and operator ownership

Assign these roles even if one person holds several:

• Customer Portal primary owner: controls organization ownership and commercial authority.
• Deployment operator: has server root access and performs install/update/recovery.
• Local Nook owner: manages workspaces and invites on the installed instance.
• Backup custodian: can retrieve protected backups and trusted revision-floor evidence.
• Security contact: receives critical release mail and owns incident decisions.

Primary owners and owners receive routine, important, and critical self-host release messages by default. Routine/important mail can be disabled; critical security or compatibility notices cannot be disabled for eligible owner roles.

Pre-install checklist

• Ubuntu Server 24.04 LTS x86_64 host, 8 GiB memory, 40 GiB operational free space plus the Portal-displayed protected staging requirement, synchronized clock.
• DNS and trusted TLS certificates are ready.
• PostgreSQL/Redis remain private; firewall and SSH policy reviewed.
• Mail provider and sender-domain authentication are ready.
• Off-host database, file, configuration, and key retention is documented.
• RPO, RTO, retention, restore floor, and recovery operator are assigned.
• Customer Portal organization and paid self-host entitlement exist.
• Connected versus air-gapped delivery is explicitly selected.
• Local owner identity and first workspace name are agreed.
• A maintenance window exists for installation and the first recovery drill.

When every item is owned, continue to Install and activate Nook.