Five secrets, generated by setup and kept by the customer.
Run every command on this page from the installation directory.
What you will achieve
When you finish this page, the customer’s secrets store holds a copy of .novuslens.env. You will know what each secret protects, and how to change one without breaking the installation.
What it is for
The secrets protect the database, the login cookieCookieA small value a browser keeps and sends back to a website. NovusLens uses a signed cookie to remember the signed-in account., stored personnel identities and requests between services. NovusLens runs in the customer profileDeployment profileA setting that selects customer or development behaviour. Customer mode refuses development credentials and uses the signed-in session as the identity., so every service refuses to start without customer values. It also refuses public development values, which anyone who can read the sourceSourceA document, interview statement, measurement or export that supports a value. Each source has a date and a stated scope. code knows.
Before you start
- Setup has run. It generates each secret once, with 64 random hexadecimal characters, and writes it to
.novuslens.env. - The customer’s secrets store is ready to receive a copy of the file before the first account or personnel file is loaded.
Steps
1. Know the five secrets
Setup writes these lines in .novuslens.env. A later setup keeps their values.
| Line | Protects | If it changes |
|---|---|---|
POSTGRES_PASSWORD | the database | do not change it; see step 3 |
CONWAY_SESSION_SECRET | the login cookie | everyone is signed out |
CONWAY_IDENTITY_SALT | the sealed personnel hashesHashA fixed-length fingerprint calculated from content. Comparing fingerprints helps detect changes and match records. | never change it; links to every stored person break |
CONWAY_SERVICE_TOKEN | requests from the web application to the reasoning service | nothing else; the deployment restarts both |
MYCELIUM_GATEWAY_TOKEN | the meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. gatewayGatewayA service that accepts requests and passes them into another system. The Mycelium gateway gives NovusLens access to the mesh. | nothing else; the data on disk is unaffected |
2. Keep a copy in the customer’s secrets store
Copy the whole of .novuslens.env into the customer’s secrets store. A backup archive also holds the file, so keep each archive as private as the file. If the installation has no .novuslens.env, a restore puts back the archive’s copy. If the file differs from the archive’s copy, the restore refuses and names the changed settings, never their values. --replace-env takes the archive’s copy. Personnel links break unless the 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. is the same.
3. Change a secret safely
Change CONWAY_SESSION_SECRET, CONWAY_SERVICE_TOKEN or MYCELIUM_GATEWAY_TOKEN when one may have been exposed:
- Generate a new value with
openssl rand -hex 32. - Replace the value on that line of
.novuslens.env. Keep the quotation marks. - Run
./lens start. Compose restarts every service whose configuration changed. - Copy the changed file into the secrets store.
- Take a backup with
./lens backup. A restore of an older archive refuses the changed file unless you add--allow-env-mismatch.
Do not change POSTGRES_PASSWORD in the file. PostgresPostgresThe database software that stores the tables read by the NovusLens screens, along with document bodies, access records and protected personnel records. sets the password once, when it creates its volume. A new value in the file no longer matches the database, so every service fails to connect.
What you will see
Setup and every later command check the file before anything starts. Each refusal names the line and the reason. When asking for help, give the line name and the refusal text. Keep the secret value out of tickets, emails and chats.
Every command output shows a secret as [secret].
When something goes wrong
| Message (abridged) | Meaning | What to do |
|---|---|---|
<NAME> cannot use a public development secret. | The value is a development default from the source code. | Generate a new value, as in step 3. |
<NAME> needs at least 24 characters. | The value is too short. | Generate a new value, as in step 3. The command produces 64 characters. |
<NAME> cannot contain control characters or line breaks. | The value was pasted with a line break or another control character. | Replace the line with the value alone. |
Set the missing field: <NAME>. | The line is missing from .novuslens.env. | Put the line back from the secrets store. |
refusing to start in the customer profile in a service’s logs | A service stopped at start-up, naming the component and every failing variable. | Correct the named lines, then run ./lens start. |
The reasoning service checks CONWAY_SERVICE_TOKEN and MYCELIUM_GATEWAY_TOKEN at start-up. The personnel ingestIngestRead supplied records or documents and add their information to NovusLens, after the required checks. checks CONWAY_IDENTITY_SALT each time it hashes. A service that refuses at start-up does not run in a degraded state; it does not start. ./lens monitor shows it as stopped, and ./lens logs shows its refusal.