Plan a Docker release change

What you will achieve

Identify what must be preserved before changing an installation’s application images or source release. The installer provides ./lens backup and ./lens restore for Compose installations. The release-change steps below remain operator-directed.

Before you start

Keep the previous release, .novuslens.env and a tested backup covering the installation’s stores. Agree a change window and a recovery procedure with the installation owner. PostgresPostgresThe database software that stores the tables read by the NovusLens screens, along with document bodies, access records and protected personnel records., all three meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. stores and installation state must remain consistent; retaining only the database is insufficient. Protect the saved credentials and identity saltIdentity saltA secret value added before employee identifiers are turned into fingerprints. Keep the same value so later imports can still match existing people. separately.

Published releases contain the application and its pinnedPinA recorded choice of one exact dependency version. It prevents an update from changing that dependency without a deliberate decision. dependencies in images. The host only needs the lens file. For a Compose installation, ./lens start --init ghcr:<tag> selects a published release and records it. Use --init dev for live source or --init local for frozen local images. A ghcr:0.x.y selection identifies an immutable release. When registry access is needed, enter your GitHub login and personal access token with read:packages permission at the prompt. For unattended commands, supply GHCR_TOKEN and GITHUB_ACTOR through the environment. See Docker deployment for image selection.

Steps

1. Prepare recovery before changing the release

Back up both primary stores through the installer:

./lens backup

The command briefly pauses the mesh nodes and archives the database, mesh volumes, installation journalsInstallation journalA saved record of setup steps, their attempts and whether they started, completed or failed. It records progress, not a backup of application data. and .novuslens.env together. The archive holds the secrets, so keep it as private as .novuslens.env. Use the installation owner’s tested recovery procedure and keep the backup outside the machine. Read Backup and restore for the command’s scope and restore refusals. Keep the existing Compose project name and mesh addresses: they locate the stored records and node identities.

2. Agree the release and migration procedure

Read the new release’s installation notes and agree how its data changes will be applied and recovered. Keep the installation directory and its saved configuration when selecting another published release. If your provider supplies a newer lens file, replace that file and run chmod +x lens. Local and development image builds require a separate source checkout. Do not assume a new directory reconnects to the previous volumes automatically.

For image choices and saved configuration, follow Installation. resume verifies and continues setup; it does not back up data or reverse an incompatible schema change. To move this installation to another published release, run ./lens start --init ghcr:0.x.y. It records the new release in .novuslens.env. Changing an image tag alone does not establish a safe upgrade. In latest mode, resume always pulls application images again, even when the setup journal records an earlier pull. Published-mode recovery checks ignore host-source edits; they use the selected images and the installer’s packaged release files.

3. Check the selected installation

After applying the agreed procedure, inspect the installation:

./lens status
./lens logs

Check sign-in, existing records and application readiness as well as containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host. health. Run an administration command with its verb. ./lens graph --help lists the verbs:

./lens graph create-viewer --help

./lens run -- <command> runs any other command through the configured Compose command service. For ./lens run, relative file paths use the installation directory, mounted as /installation inside the command service. Its generated files use that directory owner’s user and group identifiers. Arguments after -- remain literal command arguments.

To return to an earlier release, use the agreed recovery procedure for both code and data. Selecting an older image does not undo database changes.

Re-pins on the Novus side

A re-pin changes the MyceliumMyceliumThe application infrastructure underneath NovusLens. Its connected services exchange updates and keep the ordered structural log. revision used to build NovusLens. Novus engineers perform this work. They update config/mycelium.pin, rebuild the vendored Python wheelWheelA packaged Python library ready to install. A vendored wheel is stored in this repository so its exact bytes can be checked. and update the recorded release identities. Engineers run development commands directly in their task worktree. Application builds and gates use Docker; select ./lens ops --version dev for working-tree source.

The ops image builds the sidecarSidecarA separate supporting process that runs beside the application. Here it runs Mycelium and exposes the gateway that NovusLens calls. from pinned source with deploy/sidecar/gateway.patch applied. ./lens ops --version dev sidecar copies that image’s binaryBinaryA program file built to run on a particular kind of machine. A program built for one processor may not run on another. into .sidecar/; it does not build from a host Mycelium checkout. Engineers record the re-pin in config/pins.md and run the release checks for the changed code. A changed pin or successful image build does not establish that the twelve acceptance gates passed.

What you will see

Status reports the selected installation’s current state. Logs report application and Docker failures. Neither view proves that a backup can be restored; that requires a separate recovery rehearsal.

When something goes wrong

• An image cannot be pulled. Check the selected release and registry access before resuming setup.
• Existing records or mesh history are missing. Preserve surviving volumes and configuration; do not initialise a replacement over them.
• The new release cannot use existing records. Stop and use the agreed recovery procedure. Do not treat an older image as a data restore.