Deploy the stand-alone viewer
Two hosted versions are available: the stand-alone viewer, deployed independently, and the Pages preview, built from recent reviewed source and updated ahead of the stand-alone release. The preview is for early testing and may change sooner; inspect all contract details before authorizing transactions. Each origin requires its own wallet permission and browser-accessible RPC/resources.
The Pages preview is published automatically from qualified main builds. CI records its source revision, qualification run and exact built file hashes, then independently checks the published and HTTPS-served bytes. See Published-site integrity and drift. Those checks cover the Pages preview only; they do not deploy or monitor your independently hosted viewer.
Serve the generic browser application at your own HTTPS hostname. This hosts viewer software only: no blockchain, CAM bundle, contract deployment, wallet or private instance directory is created.
- Run on
- The Linux server, as its non-root Docker operator. Use that server's local Docker context, not a remote workstation context.
- Requires
- Git, Make, Bash, Python 3, Docker with Compose and Buildx; the kernel setting
net.mptcp.enabled; a hostname you control; host-side Caddy for the HTTPS example. - Changes
- A local image, a viewer container/network and the hostname's proxy configuration.
- Success
- The HTTPS health endpoint responds, the viewer setup page loads, and a known compatible app opens through a browser-readable RPC.
1. Build a known source revision
Clone the repository on the server and check out the reviewed commit you intend to serve. Use a clean checkout so the revision identifies its actual content. In that checkout, set the context and acquire the exact base images named by its Dockerfiles:
CTX=your-local-context &&
test "$(git rev-parse --show-toplevel)" = "$PWD" &&
test -z "$(git status --porcelain)" &&
make base-images/pull DOCKER_CONTEXT="$CTX" \
DOCKERFILES="containers/node-deps/Dockerfile containers/https-egress-proxy/Dockerfile containers/viewer/Dockerfile" &&
make js/deps/install DOCKER_CONTEXT="$CTX" &&
REV=$(git rev-parse --short=12 HEAD) &&
IMAGE="cam-viewer:$REV" &&
make viewer/image/build DOCKER_CONTEXT="$CTX" VIEWER_IMAGE="$IMAGE" \
VIEWER_PUBLIC_ORIGIN=https://viewer.example.orgReplace your-local-context with a local entry from docker context ls. Image acquisition and locked dependency installation are the networked preparation steps. The viewer builder then runs offline. It does not publish the image or install missing dependencies implicitly. Solidity dependencies are not needed just to build the viewer.
Set VIEWER_PUBLIC_ORIGIN to the viewer's public origin when building for deployment. The build replaces every %VARIABLE_NAME% template placeholder with its supplied value and fails if a referenced value is missing. This origin supplies the homepage canonical URL, sitemap and robots sitemap link. Generic builds without a public origin omit deployment-specific indexing metadata.
base-images/pull requires host Python 3 (standard library only) and Docker Buildx. Without DOCKERFILES, it discovers all Dockerfiles under containers/. Docker's native --call=targets,format=json parser identifies the stages without running build instructions; BuildKit may acquire a declared syntax frontend during discovery. The command checks all returned bases for literal digest pins before pulling each distinct external image once. Earlier stages and scratch need no pull; unresolved variables and explicit stage platforms are rejected. Package downloads remain separate.
Downloaded bases stay in the selected Docker engine's cache. Other builds can use the same images, so acquisition does not delete images or containers. Resource cleanup belongs to the command that owns those resources.
2. Start it on loopback
Continue in the same shell. Record the resulting image ID for updates and rollback, then start the existing runtime:
docker --context "$CTX" image inspect "$IMAGE" --format '{{.Id}}' &&
make viewer/up DOCKER_CONTEXT="$CTX" \
VIEWER_IMAGE="$IMAGE" VIEWER_COMPOSE_PROJECT_NAME=cam-viewer \
VIEWER_BIND_HOST=127.0.0.1 VIEWER_PORT=8080 &&
curl --fail --show-error http://127.0.0.1:8080/healthz &&
make viewer/status DOCKER_CONTEXT="$CTX" VIEWER_IMAGE="$IMAGE" VIEWER_COMPOSE_PROJECT_NAME=cam-viewerThe service runs in the background with restart: unless-stopped, a read-only filesystem, resource limits and its own health check. Ensure the selected Docker engine starts at server boot too; for a rootless engine this is an operator service configuration, not something the Compose restart policy establishes.
Only loopback port 8080 is exposed by this recipe. viewer/up neither builds nor pulls an image. Do not prune the previous working image while testing a replacement.
3. Put the hostname in front of it
This example assumes Caddy is installed as a host systemd service, not in another container. Follow its official installation instructions for your distribution. Point your hostname's A/AAAA records at this server and allow inbound TCP 80 and 443 to Caddy. Keep 8080 private.
Add this site block to /etc/caddy/Caddyfile, replacing the example hostname. Preserve any existing sites in that file:
viewer.example.org {
reverse_proxy 127.0.0.1:8080
}sudo caddy validate --config /etc/caddy/Caddyfile &&
sudo systemctl enable --now caddy &&
sudo systemctl reload caddy &&
curl --fail --show-error https://viewer.example.org/healthzReplace the hostname in the last command too. Caddy obtains and renews a public certificate when its DNS, port and persistent-storage requirements are met. The repository does not manage Caddy or DNS. See the upstream reverse-proxy recipe, HTTPS prerequisites and service management.
4. Open a real application
Visit your HTTPS hostname in your local browser. In Open a contract app, choose the network, enter the trusted CAM host address, and select a browser-accessible RPC. The viewing address is optional for a public view; connect a signing wallet separately when needed.
The host discovers the CAM bundle and bound business contracts. The viewer server does not proxy these resource or RPC requests by default: your browser must be able to reach them through HTTPS and the necessary CORS policy. Never place a private signing RPC credential or key in a shared link.
Verify the chain, host, loaded resources and a known read. A healthy web container proves only that the viewer is served; it does not prove an app is authentic, compatible, funded or ready for transactions. Investigate integrity warnings before signing.
Update, roll back and stop the single-container viewer
The following commands maintain the single-container setup shown above. For an isolated viewer, use the isolated update and status commands described under automatic updates; do not use these single-container commands.
Build the new reviewed revision under a new image tag using step 1. Repeat viewer/up with that new VIEWER_IMAGE and the same project, bind address and port. Check health and reopen the app. A container replacement may briefly interrupt service; this is not a zero-downtime deployment procedure.
To roll back, repeat that same startup command with the retained previous image tag or image ID. A viewer rollback does not roll back contracts, CAM publication or transactions. In a new shell, set CTX and the chosen IMAGE again before using these commands.
make viewer/down DOCKER_CONTEXT="$CTX" VIEWER_IMAGE="$IMAGE" VIEWER_COMPOSE_PROJECT_NAME=cam-viewerStopping removes this viewer's runtime, not its images or on-chain state. Remove its Caddy site block and reload Caddy when retiring the hostname; do not stop a shared proxy serving other sites.
Automatic updates from a deployment branch
make viewer/update performs one foreground attempt against origin/deploy/viewer. Publish changes to main first, then advance deploy/viewer to a commit already contained in main. Advancing that branch authorizes a release. The updater fetches both branches and refuses a deployment commit outside main before changing the checkout or runtime. It requires host Python 3 (standard library only), flock, timeout, an existing viewer built with viewer-owned revision labels, a clean deployment checkout and the same Docker context/project/bind settings as the running service. It builds on the server using the acquisition, locked dependency and offline image-build commands above.
make viewer/update DOCKER_CONTEXT=your-local-context \
VIEWER_COMPOSE_PROJECT_NAME=cam-viewer \
VIEWER_BIND_HOST=127.0.0.1 VIEWER_PORT=8080 \
VIEWER_PUBLIC_ORIGIN=https://viewer.example.orgThe target fetches the branch, selects its exact commit and compares it with the running container's immutable image and labels. Historical source without the updater is rejected before checkout, preserving the controller when selecting such releases. A healthy matching release needs no build. The checkout follows the selected commit even on that path. A replacement must reach container health and expose its full source revision in the public entry bundle. This observes the served revision; it does not prove publication integrity of every asset.
There are no deployment receipts, SHA files, settings snapshots or release directories. Docker tag cam-viewer-<project>:current protects the running image during replacement. Rollback uses the exact healthy image running before that update; there is no persistent rollback tag. After a successful update, the old image is eligible for cleanup. An empty lock under $XDG_RUNTIME_DIR serializes attempts; it is runtime synchronization, not deployment history. Temporary build inputs are removed by their creating commands. Compose retires generated dependency/compiler images; the updater removes obsolete images in its own namespace with matching viewer/project/source labels, preserving container references and other tags. Shared upstream bases remain cached.
An unhealthy starting viewer stops the update and requires recovery first. Dependency or build failure leaves the service unchanged. Before replacement, the updater checks that the starting image is still running and healthy and that the public endpoint serves its revision. Activation or public-revision failure after replacement attempts to restore that image and still returns failure. Unconfirmed rollback preserves recovery images. Cleanup failure reports failure without rolling back an accepted healthy release. Abrupt host failure or an uncatchable kill can require manual recovery.
Automatic updates support the existing single-container viewer and an explicitly migrated isolated viewer with a running ingress. For the isolated viewer, the updater replaces only the static container and checks the same ingress after activation and rollback. The selected release must support isolated updates; the running image and selected release must have compatible compose/viewer.yml and compose/viewer-isolated.yml. The updater does not perform the initial migration. Before re-enabling the timer after migration, put an isolated-capable updater in the deployment checkout and use a viewer image built from a revision containing the isolated Compose configuration. Runtime or bind/port changes still require manual migration. Historical images with inherited nginx revision labels require an initial manual build/up migration.
After one successful manual attempt, create the configured user units from the deployment checkout. All five settings are required explicitly; the Docker context name is recorded without contacting an engine. This checkout becomes the service's working directory. The checked-in templates own the timeout, umask and timer policy; host settings stay in the installed files, outside the repository.
make viewer/update/unit-files/create DOCKER_CONTEXT=your-local-context \
VIEWER_COMPOSE_PROJECT_NAME=cam-viewer \
VIEWER_BIND_HOST=127.0.0.1 VIEWER_PORT=8080 \
VIEWER_PUBLIC_ORIGIN=https://viewer.example.orgThis creates cam-viewer-update.service and cam-viewer-update.timer in $XDG_CONFIG_HOME/systemd/user/ (normally ~/.config/systemd/user/) and reloads systemd. It neither enables nor starts them. If either file already exists, including a symlink, creation refuses before writing either file. Existing installations need no move, override file or replacement. If reload cannot be confirmed after creation, the completed files remain; retry systemctl --user daemon-reload. Keep host account names, private listeners and full operator paths out of the repository.
make viewer/update/timer/enable-and-start
make viewer/update/timer/status
make viewer/update/service/logs/recentenable-and-start enables the timer for subsequent user-manager starts, then starts it now; a due timer may trigger an update immediately. Status shows timer loading, enablement, active state and scheduling, plus the last update-service result; an inactive successful oneshot service is normal. Recent logs print the last 100 journal entries for the update service and exit without following. Foreground viewer/update output goes to its caller's terminal, not this service journal. Management recipes do not select a Docker engine; the service uses its configured context. Unattended operation after logout/reboot requires user lingering and an available selected Docker engine; these targets configure neither.
The timer runs one minute after completion; overlapping manual attempts fail the same lock. The complete attempt has a twenty-minute deadline with bounded cancellation/recovery grace. A failed attempt retries at the next timer activation. Before manual rollback, run make viewer/update/timer/disable-and-stop: it disables automatic activation, then stops the timer. An update already running continues; let it finish before rollback. Use viewer/up for the single-container viewer, or viewer/isolated/viewer/up for the isolated static viewer, with the chosen compatible image ID and the same runtime settings. Successful updates do not retain a previous release for later manual rollback; build it again if needed. Use viewer/isolated/status to inspect the isolated viewer and ingress. Re-enable the timer after correcting or moving the branch.
On a dedicated builder, configure an appropriately small native BuildKit garbage-collection budget. The updater does not change shared engine policy or run engine-wide prune. Container logs are already rotated by the runtime; bound journal storage through the host's existing journal configuration.
Check the failing boundary
| Symptom | Next check |
|---|---|
| Required local base image missing | Repeat explicit acquisition for the Dockerfiles at your selected revision and context. |
| Container fails before health | Check the image exists on that engine, port ownership, and the kernel's per-namespace MPTCP setting. Do not remove confinement to hide the failure. |
| Loopback health works; HTTPS fails | Check DNS, firewall, Caddy configuration and journalctl -u caddy. |
| Viewer loads; app does not | Check browser console/network errors, chain/host coordinates, browser RPC access, resource CORS and Download scope. |
Implementation baseline: image builder, portable runtime and the viewer Make targets. Hosting CAM resources and deploying contracts are separate tasks.