Start it, check it, stop it, and say what stopped.
What you will achieve
Start the installation with one command, then check that each service is healthy and the analysis is current. Stop the installation and keep its records. Run every command here from the installation directory.
What it is for
The services are the twinTwinNovusLens’s model of one organisation, built from records about its teams, services and how they rely on one another. It is only as current as those records.. They must keep answering, and the read modelRead modelThe database tables used by the map, Ask and Find. NovusLens rebuilds these tables from its history of recorded changes. must keep up with the log.
The operator needs one view that says whether the picture is current. ./lens monitor gives it.
Before you start
Complete Installation. ./lens setup saves .novuslens.env and runs the first deployment.
The commands
| Command | What it does |
|---|---|
./lens start | Starts the saved installation. It checks the host, gets the images, runs initialisation, starts every service and waits until each is healthy. Then it opens the monitor. |
./lens resume | Continues an interrupted deployment. It repeats only missing or stale steps. |
./lens monitor | Shows the live state of each service, the meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log., the read model, the model server and the setup journalInstallation journalA saved record of setup steps, their attempts and whether they started, completed or failed. It records progress, not a backup of application data.. |
./lens status | Prints the setup journal, then every containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host. with its state. Starts nothing. |
./lens logs | Prints the last 100 lines from each service. |
./lens stop | Stops and removes the containers and the installation’s network. The data volumes stay. |
./lens deploy is another name for ./lens start.
Add --no-monitor to start or resume to exit when deployment finishes.
For a longer log from one service, run ./lens compose -- logs --tail 500 reasoning.
start, step by step
start records each step in the setup journal. ./lens status shows them.
- Configuration. It checks that
.novuslens.envmatches the saved answers. - Preflight. It checks Docker, Compose and the configuration.
- Images. It signs in to GitHub Container RegistryGitHub Container RegistryGitHub’s service for storing and downloading packaged applications used by Docker. and pulls the published images, or builds the images from source.
- Model server. For a
localmodel server, it starts Ollama and downloads both models. - Initialisation. The one-off
initservice connects to PostgresPostgresThe database software that stores the tables read by the NovusLens screens, along with document bodies, access records and protected personnel records., applies the database migrationsMigrationAn ordered change to a database's tables or rules. Applied migration files are recorded so the same file is not run again., loads the GuideGuideThe help pages inside NovusLens. They explain the pages, input formats and tasks in the version you use. They are product instructions, not evidence about the organisation., loads the chosen demo and creates the initial operator account. It waits for Postgres and the three mesh nodes to be healthy first. - Application. It starts every service and waits up to 300 seconds for each health check to pass.
- Meridian. When you chose the Meridian demo, it loads Meridian in a one-off container.
The installer then prints the sign-in address, by default http://localhost:3111/login.
The services
| Service | What it runs | Health check | Restarts |
|---|---|---|---|
postgres | The read-model database. | pg_isready | Yes |
mesh-0, mesh-1, mesh-2 | The three MyceliumMyceliumThe application infrastructure underneath NovusLens. Its connected services exchange updates and keep the ordered structural log. mesh nodes that hold the canonical logCanonical logThe permanent history of changes to an organisation’s model. New entries are added at the end. Earlier entries stay when the database is rebuilt.. | Each gatewayGatewayA service that accepts requests and passes them into another system. The Mycelium gateway gives NovusLens access to the mesh. answers /health on port 8400 inside its container. | Yes |
init | One-off initialisation, at each deployment. | Must exit successfully. | No |
reasoning | The reasoning service on port 8500. | /health answers. | Yes |
projector | The projectionProjectionThe regular pass that brings the read model up to date with the canonical log. It runs every 30 seconds by default. loop. It advances the read model every NOVUSLENS_PROJECTION_INTERVAL seconds. | None. The monitor shows the age of its last pass. | Yes |
ui | The web application. | /login answers. | Yes |
ollama | The local modelLanguage modelSoftware that produces text from instructions and supplied context. NovusLens checks its answers against the records retrieved for the question. server, only for a local model server. | ollama list | Yes |
Services marked Yes use Docker’s unless-stopped policy. Docker restarts one that exits, and starts them again when the Docker engine restarts.
reasoning, projector and ui start only after init has finished successfully. ui also waits for reasoning to be healthy.
./lens monitor shows each container’s restart count. A rising count means the service keeps failing. Read its log for the error that ends each run.
Storage
./lens stop keeps these Docker volumes. Compose prefixes each name with the project name, novuslens-demo by default.
| Volume | Holds |
|---|---|
postgres-data | The read-model database. |
mesh-0-data, mesh-1-data, mesh-2-data | Each mesh node’s write-ahead logWrite-ahead logA file that records changes before they are reflected in stored data, so the changes can be restored after a restart. and snapshots. |
installation-state | The initialisation journal. |
ollama-data | Downloaded models, for a local model server. |
Retained volumes are not a backup. See Backup and restore.
Ports
Only the web application publishes a host port, 127.0.0.1:3111 by default. Set it with NOVUSLENS_UI_PORT.
The other ports stay on the installation’s private Docker network:
| Port | Service |
|---|---|
| 8500 | Reasoning service |
| 8400 | Each mesh node’s gateway |
| 57010 | Each mesh node’s gossipGossipA way for connected services to pass updates to one another until the updates spread through the group. |
| 5432 | Postgres |
Readiness and health
Two endpointsEndpointA particular address on a service that accepts a defined kind of request. on the reasoning service report health. Both answer without a service tokenService tokenA secret value sent with requests between NovusLens services. The receiving service refuses requests with a missing or wrong value., so Docker’s health check and the monitor can read them.
GET /health on port 8500 checks the database and the mesh gateway. It returns 200 with {"status":"ok","problems":[]} when both answer. Otherwise it returns 503 with "status":"degraded" and a problems list. A problem reads database: <error type> or mesh gateway: <error type>.
GET /ready on port 8500 reports whether the read model is being advanced. It returns 200 when the status is ready or degraded, and 503 when it is failed or stale. The fields are:
status:ready,degraded,failedorstale. Degraded means a stage failed on a recent pass. Failed means materialisation failed and the picture is not advancing.projection_age_sandlast_success_age_s: the age of the last attempted pass, and of the last successful one, per organisation.stale,failedanddegraded: the organisations in each state.errorsandwarnings: detail per organisation.max_age_s: the age limit that was applied.
/ready uses a default limit of 90 seconds, three times the default projection interval. Before the first pass has been recorded, every organisation is stale, so /ready returns 503 for a few seconds after a fresh install.
The reasoning port is not published to the host. To read /ready, use the query in Read the analysis status.
Projection interval
NOVUSLENS_PROJECTION_INTERVAL is the number of seconds between projection passes. Each pass advances the read model from the log for every organisation.
The default is 30 seconds, and the minimum is 5. Setup refuses a smaller value.
To change it, edit the line in .novuslens.env, then run ./lens start.
/ready keeps its 90-second limit whatever the interval. With an interval near or above 90 seconds, it reports stale between passes.
What you will see
startends with the sign-in address, then opens the monitor.- The monitor shows every service healthy and a recent read-model pass for each organisation.
./lens stopremoves the containers and keeps the volumes.
When something goes wrong
- A service shows a rising restart count. Run
./lens compose -- logs --tail 200 <service>and read the error that ends each run. startstops at a step. Correct the printed error, then run./lens resume.- The read model is old, or readiness is
failed. Read the projector’s log with./lens compose -- logs --tail 200 projector. Then follow installation diagnostics. - Readiness is
degraded. A stage other than materialise failed on the last pass. The picture may be older than the records. The error names the stage. - The web port is in use. Follow the port change steps.