Installation

Every NovusLens installation starts with one command: ./lens setup. It asks a few questions, saves the answers in .novuslens.env and starts NovusLens with Docker ComposeDocker ComposeThe Docker tool that starts and connects the services listed in one configuration file.. A demonstration and a customer’s own installation use the same command.

Choose where the images come from

Without --init, setup chooses for you and prints its choice:

• In a git checkout, it builds from that source, as --init local.
• Anywhere else, it pulls the published release this lens file was built for, as --init ghcr:<release>.

Setup records the choice, so later commands do not repeat it. Run ./lens version to see it. An installation keeps its mode. To try another mode, use a new installation directory. To move a published installation to another release, run ./lens start --init ghcr:<version>.

Before you start

You need:

• Linux or macOS, with Python 3.9 or newer. Most hosts already have it.
• Docker  with its Compose plugin, and a running engine.
• A host account that can use Docker and keep the installation files private.
• Internet access to download images. Source builds also download build dependencies and the pinnedPinA recorded choice of one exact dependency version. It prevents an update from changing that dependency without a deliberate decision. MyceliumMyceliumThe application infrastructure underneath NovusLens. Its connected services exchange updates and keep the ordered structural log. source.
• Storage for images, records and any model weights you choose. Local models need enough memory and disk for both models.

You do not need Node, Rust, PostgresPostgresThe database software that stores the tables read by the NovusLens screens, along with document bodies, access records and protected personnel records. or Ollama on the host. Every component runs in Docker. Run ./lens doctor to check Python, Docker and Compose. It names the fix for each problem it finds.

To get the lens file, open the download site . Ask Novus-i2 for the password, then choose a release and download lens. The site holds lens and the installation steps. Setup downloads the application separately.

For published images, copy only the lens file into a new, empty directory. Setup writes its Compose files and downloads the images. Published images come from GitHub Container RegistryGitHub Container RegistryGitHub’s service for storing and downloading packaged applications used by Docker. (GHCR). Setup asks for your GitHub login and a personal access token with read:packages permission.

Network and ports

Only the web application publishes a host port: 127.0.0.1:3111 by default. The database, the meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. gatewaysGatewayA service that accepts requests and passes them into another system. The Mycelium gateway gives NovusLens access to the mesh. and mesh traffic stay on Docker’s private network. For browser access from another machine, put an HTTPSHTTPSHTTP carried over an encrypted connection, so the contents are protected while travelling between the caller and the server. proxyProxyA service that receives a request and forwards it to another service. The NovusLens web proxy adds the signed-in identity and service token. in front of the web application. Keep the other services private.

What setup asks

Setup asks for the web port, a private network range, the first operator login and passphrase, a model server and the demo to load. Setup settings lists every question, its default and the line it writes in .novuslens.env.

Save the operator passphrase in your password manager. If deployment stops, run ./lens resume from the same installation directory.

Keep private files separate from source

To keep the configuration and setup records in another directory, pass --directory /absolute/path/to/installation on every ./lens command. That directory holds .novuslens.env, 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. and the files used by administration commands. It does not need a source checkout. ./lens mounts it at the same absolute path inside the installer containerContainerA running program with its own packaged software and isolated environment, managed by Docker on the host..

local builds from the source packaged in the selected installer image, and dev mounts the live checkout. Neither reads application source from the private directory. Running several installations side by side needs a separate directory, Compose project name, network range and host port for each.

Preserve the installation

The installation stores Postgres and each mesh node in Docker volumes. A stop keeps them. Retained volumes are not a backup.

./lens backup [DEST]
./lens restore <archive.tar.gz> --yes [--allow-release-mismatch] [--replace-env | --allow-env-mismatch]

backup needs Postgres running. It briefly pauses the mesh nodes while it copies their volumes, then dumps the database. The archive holds the database, the three mesh volumes, the installation-state volume, the release manifestRelease manifestThe file recording the exact software versions and fingerprints used for a NovusLens release candidate. Installation checks compare files against it., the setup journal and .novuslens.env. Only your user can read it, because it holds the secrets. restore needs no earlier setup --init; it puts the archive’s .novuslens.env in place when the installation has none. DEST must be inside the installation directory. The default is its backups/ directory.

Keep each archive as private as .novuslens.env, and keep a copy on another disk or host. restore checks the file’s recorded checksum and the release and image identity. It stops the services, backs up the current volumes when they exist, restores all four volumes and the database together, then starts the installation. The mismatch flags skip their checks. Use them only after a deliberate change.

Test a restore before relying on it. Backup and restore covers the details. The engagement kit  keeps fictional rehearsal data apart from customer data.

Delete a demonstration

Run ./lens delete in the installation directory. It creates .lens-prep-to-delete and prints the confirmation command with the recorded installation type. For example, an installation created with --init ghcr:latest needs:

./lens delete
./lens delete --yes-i-am-sure ghcr:latest

For a separate installation directory, pass the same --directory on both commands. The type must match the spelling recorded during setup, including the version. If the configuration changes after preparation, remove the marker and prepare again.

Deletion checks the saved project and installation directory before it removes anything. It identifies the installation’s containers from the configuration path Compose records on them, then their attached storage and networks. If it cannot establish that a resource belongs to this installation, it refuses and removes nothing. If another installation uses the same project name, deletion prints that directory’s delete command instead. The marker keeps the checked resource identities, so a cleanup that fails partway can resume. Correct the printed error and repeat the confirmation command. A successful deletion says how many containers, networks and volumes it removed, and removes the marker and setup records.

Next steps

• Install a demonstration with the Quick start.
• Read every setup question in Setup settings.
• Run, stop and restart the installation with Start and stop.