Install the matching compiler
Use the server release’stools/pages-build directory:
sha256:… ID, not a mutable tag. The compiler never
pulls an image or installs project dependencies during a Page build. New builds
verify that the image’s SDK/compiler/dependency fingerprint matches the server.
A mismatch is an installation error with an instruction to rebuild the image.
The Go service needs git in PATH, access to Docker, and a protected absolute
CREWSHIP_PAGE_PROJECTS_PATH outside agent/crew mounts. The service account must
own the directory; source files must not be served as a public filesystem tree.
The build container uses UID 1001 and receives no crew mounts or credentials.
Configure the browser-facing origins
Example configuration for an existing Go service:studio.example.com and apps.example.com are insufficient.
Both origins need DNS and certificates trusted by the viewer’s browser. Internal
DNS/CA are acceptable when clients are configured to trust and reach them.
Point the runtime reverse proxy at the same Crewship Go listener, preserving its
runtime Host header. Route only /api/v1/pages/runtime/bootstrap on that host and
return 404 for other paths. Do not strip or weaken Crewship’s CSP/frame headers.
The browser origin (CREWSHIP_PAGE_STUDIO_ORIGIN) uses the existing
authenticated application proxy configuration.
A hosts-file entry on the server is not browser DNS. Verify from a viewer machine:
/pages/{slug} alone only proves the static shell is served.
CREWSHIP_PAGE_RUNTIME_DEVELOPMENT_SAME_ORIGIN=true is a deliberate development
exception, off by default. It must use exactly the browser origin and shows an
isolation warning. It is not a production substitute for the second site.
Verify a clean installation
Start with a fresh Crewship data directory and the normal administrator setup. Using an authorized owner/crew, create a Page with an existing local producer and a declared harmless routine. Then initialize the shipped starter, pack/save it, build it and explicitly review/publish it with the CLI or the page editor’s review (Edit → Content). Commands and expected-revision flags are documented in Page CLI. Run these checks before accepting the installation:bash scripts/test-pages-apps.sh rebuilds the tools
image, runs real Docker/API/MCP/seed checks and exercises the Go bootstrap in
Chromium. It fails when required tests are skipped. It does not replace a real
chat-agent authoring test or your deployment’s DNS/TLS verification.
Storage and recovery
Storage quotas apply across a workspace. Retention keeps required draft, live and running-build roots plus bounded optional history; optional history can be reclaimed before saves/builds when storage is under pressure. Older Git ancestry is truncated at retained checkpoint boundaries without changing the retained commit hashes. Backups carry those boundaries and complete retained source trees. Administrators can reclaim eligible storage without removing active roots:crewship page project fsck <slug> compares referenced source/artifact digests and
checkpoint definitions with SQL. It prints diagnostics and exits nonzero on failed
integrity checks; it does not silently repair data. Restore a verified backup or
investigate the named root. Temporary build persistence failure is reported as
interrupted; compiler diagnostics remain failed with their original error.
Upgrade and rollback
Before upgrade, take a complete workspace backup and preserve the current server binary/version and tools-image digest. Install the new server and its matching pinned compiler image as one release. Existing published artifacts continue to run; upgrade does not automatically rebuild or republish customer applications. Use an unpublished draft for a rebuild with the new profile. Compare the preview, SDK interactions and action declarations, then explicitly publish. If compilation fails, the previous publication stays live. Image fingerprint mismatch requires a matching image; do not disable the check or change the lockfile to work around it. V1 profile/SDK maintenance must keep existing source contracts compatible; a breaking change requires a new explicit profile and migration instructions. A portable source file does not promise byte-identical output on a different release. Keep old images for rollback, subject to your installation’s security update policy. Publishing a Page freezes its UI and declared action binding, not a routine’s code. The confirmation dialog and receipt expose definition drift. The routine runner continues to use the routine’s current definition and scripts, so sensitive operation approval must also follow that routine’s own governance. What a publication is fenced on is the routine definitions the reviewer was shown: the review snapshot lists a digest for every routine acall action
would run, the publication sends them back as expected_routine_digests, and
the server recomputes and compares them inside the publishing transaction. A
routine that changed between the review and the click — an upgrade that
rewrote its script, a maintainer editing it — refuses the publication with
409 and conflict: "routines", naming the routines that moved. So when you
upgrade or edit routines that Pages call, expect in-flight reviews to be
refused and re-reviewed; that is the fence working, not a failure to work
around. crewship page project review <slug> shows each routine’s current
state (unchanged, changed, unknown) before anyone publishes.