4. Interactive installation

Back to overview · Full table of contents · Download full PDF

This chapter: it follows the installer's actual order in the terminal, from preflight and startup through each question screen, install execution, post-install acceptance, and the completion output. It states what each screen shows, what to fill in, and how to handle exceptions, then how to resume after an interruption. The reader is the implementation engineer working on the install host. Screens that involve the database, storage, or network need the matching customer administrator present, or prepared in advance per Chapter 3.

4.1 Install flow

The installer's full sequence is below. Before confirm-install it writes no files and creates no services. Typing q at any step leaves nothing on the host (exit code 130). The questions have no "go back". If you fill something in wrong, type q and start over, or change the matching question as prompted before the confirm page.

Note: from step 11 onward the installer records progress under /opt/zenova/state/. After an interruption or failure, rerun the same command to continue from the breakpoint (section 4.8). Do not delete any files by hand.

4.2 Run preflight first

Applies to: before the real install, confirm host conditions and the answers on the install host. Preflight can be run repeatedly and leaves nothing behind.

Prerequisite: artifacts have been placed in /root/zenova-install and verified per section 3.6.

Procedure

1. Enter the staging directory, set the offline-package variable, and run preflight.

# Install host · root · read-only (preflight; writes nothing)
cd /root/zenova-install
ZPKG=/root/zenova-install/<offline-package>.zpkg
sudo ./zenova install "$ZPKG" --check-only

2. Answer the capability, prefill-confirm, and extra-configuration screens as in section 4.4. Answers given in preflight are not saved; you will answer again during the real install. Use preflight to settle the answers and write them down.
3. When the host check has ✗ items, follow the on-screen prompt and Chapter 3, then press Enter to recheck.
4. When the install directory must sit on another data volume, pass the same flag on preflight, for example --install-dir <directory>; otherwise the check is the default /opt/zenova.

What you will see

• The last line is "Preflight passed: nothing was written", and the command exits.

Note: preflight does not include the following checks. Passing preflight does not mean the real install will pass:

4.3 Start the install

Prerequisite: preflight has passed; customer administrators are in place (when using existing dependencies, the database administrator and storage administrator must be present to enter passwords, or a secrets file is ready).

Procedure

1. Run inside a tmux or screen session when the host already has one, so an SSH disconnect does not interrupt the install.
2. Run the install command.

# Install host · root · write (install starts after confirmation)
cd /root/zenova-install
sudo ./zenova install "$ZPKG"

3. Check the first line on screen, "Will install: <product> <version>". If it is wrong, type q and exit.

Main flags (interactive install usually needs none of them; use as needed):

What you will see

• The first line looks like "Will install: Zentrix Gateway 0.7.0-nightly.20261020034227.f51c370a".

Note: the product name on the first line is decided by the installer; the version number comes from the offline package. Check two things: whether the product is the one this engagement will deliver (the product cannot be changed after install, only wipe-and-reinstall); and whether the version matches the handover record. When the installer and offline package differ in version or product, the installer refuses before this line and states the reason.

4.4 Screen by screen

The screens below appear in this order. Items already prefilled by the customizer site are not asked again; they are confirmed together on the Confirm prefilled settings screen.

4.4.1 Choose capabilities

What you will see

• Title: "Capabilities to install this time (core is always installed; items not selected stay on this host and can be enabled later from the console)", then the capability list from the offline package, with numbers and selected state.
• Prompt: "Type a number to toggle; press Enter when done".
• A first Zentrix Gateway install selects only Core by default; the full edition selects every capability in the offline package by default.

Procedure

1. Type a number to toggle that item. You can type more than once.
2. After checking the selection, press Enter.

Note: Core is always installed and cannot be cleared. Dependencies are linked automatically: selecting Document parsing also selects Knowledge base. Capabilities present in the offline package but not selected this time stay on the host and can be enabled after install from System Updates, without downloading again. Selection affects disk need (section 3.1); when disk is tight, select only the capabilities this engagement will actually verify.

4.4.2 Confirm prefilled settings

Applies to: step 4 on the download site filled in prefilled settings. This screen is absent when the whole page was left blank.

What you will see

• Title: "The following settings come from the customizer site", listed at two levels:
  • Ordinary items (access URL, dependency deployment mode, object-storage mode, notification-channel type) listed together, with "press Enter to confirm, or type n to change".
  • Address-type items (addresses of existing PostgreSQL, ClickHouse, and object storage, and the notification-channel address) shown one by one and marked "from the customizer site", with "type y to confirm this item".

Procedure

1. For ordinary items, press Enter if they are correct; type n to change, and the installer asks again.
2. For address-type items, type y one by one to confirm; refusing makes the installer ask you to rewrite the value on the spot.

Note: prefilled content is marked unsigned in the offline package. Address-type items must be confirmed with y one by one; pressing Enter is not confirmation. That prevents an address from being changed while the offline package is in transit.

4.4.3 Access URL and local listen port

What you will see

• "Access URL (press Enter to use this host <host-address>; you may also fill in http://… or https://…; the port written in the URL is the local listen port; with no port it is 80)".

Procedure

1. Fill in the access URL using the table below. Press Enter to use this host's address http://<host-address>.
2. When the access URL is http:// and carries a non-80 port, the installer then asks whether a proxy or NAT sits in front of the access URL:
   • Choose "No, this host listens on the port in the access URL" and this host listens on that port;
   • Choose "Yes, a proxy or NAT forwards to another port on this host", then fill in "Local listen port (the port the proxy, NAT, or TLS ingress forwards to; press Enter for 80)".
3. When the access URL is https://, the installer asks directly for the local listen port the TLS ingress forwards to; press Enter for 80.

Note:

• The access URL is what users and callers finally use. Filling in https:// does not make this host serve HTTPS; the customer's load balancer or reverse proxy terminates the certificate.
• When the port in the access URL differs from the local listen port, a front proxy, NAT, or TLS ingress must forward the access-URL port to the local listen port; otherwise the access URL will not open.
• With an http:// access URL, the sign-in page does not offer passkeys, and two-factor authentication can use only an authenticator app. If the customer needs passkeys, the access URL must be https://.
• A malformed address prompts "the access URL must be a complete address starting with http:// or https://"; fill it in again on the spot. A single-label hostname with no dot that does not resolve is flagged as a risk and requires y to continue using it.

4.4.4 Platform database (PostgreSQL)

What you will see

• "Platform database (PostgreSQL)", two options: Deployed by us and Use an existing service.

Procedure

1. With no special requirement, choose Deployed by us: the installer initializes PostgreSQL on this host, listening on loopback only, and asks nothing further.
2. When you choose Use an existing service, fill in, in order:
   • "Platform database address (host:port)", for example <database-address>:5432;
   • "Platform database administrator account (must be a superuser; the installer uses it to create the platform roles and databases)";
   • "Platform database encryption": Plaintext (no encryption), Encrypted (verification delegated to the system trust store), Encrypted and verified with a specified CA certificate; default is plaintext. The third option then asks for "CA certificate file path", which must be a file that already exists on the install host.

Note: it does not ask for a database name. The platform databases are created by the installer and the names are fixed. The administrator-account password is entered on the later Credentials screen. Requirements and the database-administrator self-check are in section 3.5.

4.4.5 Analytics database (ClickHouse)

What you will see

• "Analytics database (ClickHouse, required)", two options: Deployed by us and Use an existing service.

Procedure

1. With no special requirement, choose Deployed by us.
2. When you choose Use an existing service, fill in, in order:
   • "Analytics database address (host:port)", the HTTP or HTTPS interface port (commonly 8123 / 8443), not 9000;
   • "Analytics database name (press Enter to use zenova)";
   • "Analytics database login account", default per section 3.5;
   • "Analytics database encryption", the same three options as PostgreSQL;
   • "Analytics database type": Standalone database (ordinary MergeTree) or Replicated database (engine Replicated, DDL with ON CLUSTER); default is standalone; choose what the database administrator told you.

Note: ClickHouse is required; there is no "do not install" option. When this host's CPU instruction set does not meet the requirement, the host check offers "reselect the analytics database", which returns to this screen so you can switch to Use an existing service (section 4.4.8).

4.4.6 Object storage

What you will see

• "Object storage", three options: Bundled object storage (recommended, production), Local directory (single-host trial), Existing S3-compatible storage; default is the first.

Procedure

1. For a single-host install, the recommended choice is Bundled object storage (recommended, production). The installer deploys it on this host and creates the buckets.
2. For a short trial you may choose Local directory (single-host trial).
3. When you choose Existing S3-compatible storage, fill in, in order, "Object storage address (http://… or https://…)", "Region", "Bucket", and "Object-storage addressing" (Path-style or Virtual-hosted; default path-style). Access keys are entered on the Credentials screen.

Note: the object-storage mode cannot be changed online after install. To change it you must back up, reinstall with the new choice, then restore. An environment that will move from POC to production should be filled in with the production choice here.

4.4.7 Operations-notification channel

What you will see

• "Operations notification channel", options: DingTalk, Feishu, WeCom, Webhook, Skip for now.

Procedure

1. Choose the type, then fill in "Channel address" (the full robot or callback URL, which must start with http:// or https://).
2. When a DingTalk robot has signing enabled, fill in the key from the robot's Security settings › Sign under "Signing secret"; input is hidden. Leave it blank when signing is not enabled. A webhook secret is likewise optional.
3. Before the confirm page the installer sends a test message (section 4.4.11). You may also choose Skip for now and continue, then add a channel later on the Notification channels page. With no notification configured, notification binding and notification-egress acceptance show as skipped and do not block the install; the alert engine and other checks still run. An existing notification configuration that was not verified, or that failed to send, still errors. The channel filled in at install receives every platform alert. Urgent notifications need a separate channel created after install on the console Notification channels page and set as Urgent notifications (section 6.5).

4.4.8 Host check

What you will see

• Title "Host check", then each result: ✓ pass, ⚠ warning, ✗ block. Items include CPU architecture, memory, disk space, system service manager, and system time, plus processor instruction set, container runtime, directory traverse rights, mount execute rights, and service-user attributes when they apply to this selection.
• When System time passes, a line below shows "synchronized, offset N seconds (pre-install limit 30 seconds)".
• Failed items list the reason and the remedy one by one. The remaining checks still run after the first failure.

Procedure

1. All ✓, or only ⚠: continues automatically.
2. Any ✗: in another terminal, follow the on-screen prompt and Chapter 3, then return to the installer and press Enter to recheck; type q to exit.
3. When the only block is Processor instruction set, you can choose "reselect the analytics database" and switch the analytics database to Use an existing service.

Note: when --install-dir is passed explicitly (including writing /opt/zenova out), insufficient disk shows as ⚠ and continues. That only means it does not block; if space is actually short, unpack, install, or runtime can still fail.

4.4.9 Ports

What you will see

• When a platform-internal service port is in use, the installer automatically switches to the next free port and states each change; no action is needed.
• When the business-ingress port is in use, it shows "local listen port <port> is occupied by process <process-name> (PID <pid>). The access URL depends on this port, and the install will not pick another port automatically; …", and prompts "after freeing the port, press Enter to recheck; type n to refill the access URL and local listen port; type q to exit".
• When the business-ingress port equals a platform-internal port, it states that this port is used by a platform-internal service and cannot be an access ingress.

Procedure

1. When the business-ingress port is in use, stop the occupying process after confirming with the customer, return to the installer, and press Enter to recheck.
2. When the occupying process cannot be stopped, type n and refill the access URL and local listen port. If --business-entry-port was passed on the command line, you cannot change it in the questions; type q to exit and rerun with another port.
3. When the admin ingress is split and its port is in use, it advances automatically to the next free port. Direct access on this host in the completion output uses the port actually assigned.

Note: this screen does not appear in preflight. After you change the local listen port, the port in the access URL and the local listen port may no longer match; a front forward is then required (section 4.4.3).

4.4.10 Credentials and dependency probe

Applies to: at least one dependency chose Use an existing service. This screen is absent when the installer deploys all three.

What you will see

• It asks, in order (input is hidden): "password for platform-database administrator account <account>", "analytics-database login password", "object-storage access-key ID", "object-storage secret access key", only for the items that chose Use an existing service this time.
• It probes immediately after entry. When everything passes it goes to the next screen. When something fails, the title is "Dependency probe", each line is "<dependency>: <reason>, contact <owner>", and it prompts "after the fix, press Enter to reprobe; type q to exit".

Procedure

1. The database administrator and storage administrator enter passwords and keys at the terminal themselves. Do not write the password into chat history or onto paper to hand over.
2. When a probe fails, follow the reason and owner listed on screen (self-check against section 3.5), then press Enter to reprobe.

What is probed:

Note: the probe creates and then deletes a temporary database (zenova_probe_<random>) or a temporary object (zenova-probe/<random>). It does not write business data. The PostgreSQL administrator password is used only during install and is not written to any file or log. After install the platform uses only its own roles to access the database.

Note: if the platform databases in existing PostgreSQL already hold platform data, an ordinary install stops here and tells you to use a takeover install (--adopt-existing). Takeover is out of scope for this chapter; contact support and confirm before proceeding.

4.4.11 Operations-notification test

Applies to: a notification channel was configured in section 4.4.7.

What you will see

• Send succeeded: "Test message sent; confirm it was received".
• Send failed: "Operations-notification test: <failure reason>". You can correct the channel address or signing secret and resend, type s to skip notifications, or type q to exit.

Procedure

1. Confirm the test message arrived in the matching group or receiver.
2. On send failure, check the channel address, robot security settings, and egress from the install host; correct the address or signing secret as prompted and resend. If it cannot be configured yet, type s to skip notifications and finish the configuration after install.

Note: the installer checks business error codes returned by the channel. A rejected signature, token, or keyword check is not shown as sent successfully. After "sent", still confirm in the group that the recipient received it.

4.4.12 Confirm page

What you will see

• Title "About to start installation; confirm the following", listing:
  • Access URL, followed by "local listen port". When they differ: "the port in the access URL differs from the local listen port; a front proxy or NAT must forward the access-URL port to the local listen port". When the access URL is https://: "the access URL uses https; a front TLS ingress must terminate encryption and forward to the local listen port".
  • Choices and addresses for the platform database, analytics database, object storage, and operations-notification channel.
  • "Capabilities: …".
  • "Install directory: /opt/zenova (needs N GB disk)"; when --install-dir was passed explicitly it shows "recommended".
  • "Service account zenova: ancestor directories outside the install root must be traversable; system-directory permissions are managed by the system administrator".
• Last line: "Confirm and start installation".

Procedure

1. Check each item against the handover record, especially the access URL, local listen port, and object-storage mode.
2. If correct, press Enter to confirm; if not, type q to exit and rerun the install command.

Note: this is the last point that does not write to disk. After Enter, the installer starts writing deployment configuration and unpacking the offline package. Exiting after that leaves a partial install, which can only be resumed per section 4.8 or handled through wipe-and-reinstall.

4.5 Install execution

What you will see

• It first unpacks the offline package and, as the service user, checks whether bundled programs can run. When a security module intercepts, it lists ✗ [<code>] <reason> <remedy> line by line and stops (remedy in section 3.3, then resume per section 4.8).
• It then runs four stages. Each stage starts with "Installing: <stage>" and ends with "<stage> completed".

• After the four stages it prints a "time per stage" table, and "per-item timing and migration step timing have been written to the install log".

Procedure

1. Wait for the install to finish; do not interrupt. On a clean host where the installer deploys all three dependencies, the whole run is about 4 minutes. Database migration is about half of that; a long stay in the control-plane stage is normal.
2. To watch details, open another terminal and follow the install log:

# Install host · root · read-only (follow the install log)
tail -f /opt/zenova/state/install.log

When --install-dir was used, replace /opt/zenova with the actual install root.

Note: when a stage fails, the screen stops on the failed step and gives the reason and the next action. After fixing the cause, rerun the same install command; completed stages are skipped (section 4.8). The console is unavailable during install. A first install has no gateway business traffic yet and does not affect any existing business.

4.6 Post-install acceptance

Post-install acceptance is the last install stage. It runs automatically and needs no input. The install is recorded as complete only when every blocking acceptance item passes.

What you will see

• Acceptance passed: the completion output in section 4.7, which includes the acceptance result.
• Acceptance failed: the screen shows "Post-install acceptance failed: checks that did not pass: <item> (<evidence>)", and the install is not recorded as complete.
• A failed warning-level item is only a hint and does not prevent the install from completing.

Procedure (when acceptance fails)

1. Follow the reason in evidence. Common cases:

2. After the fix, rerun the same install command. The installer continues from post-install acceptance and does not redo earlier stages.

# Install host · root · write (continue from post-install acceptance)
cd /root/zenova-install
sudo ./zenova install "$ZPKG"

3. When remote support is needed, collect information:

# Install host · root · read-only
sudo zenova status --json > /root/zenova-install/status.json
sudo zenova doctor --all --save /root/zenova-install/doctor
sudo cp /opt/zenova/state/install.log /root/zenova-install/

Note: passing post-install acceptance only proves that platform base services are usable. Model and tool configuration, a real call, and the deny path are completed item by item in Chapter 7.

4.7 Completion output

What you will see

After the install finishes, the screen prints, in order:

• The "time per stage" table and the acceptance result;
• "Installation complete";
• "Admin-console sign-in account (the initial password is stored only on this host and is not written to logs)", then login account root and a 32-character random initial password (the exact line format follows the actual output);
• "Direct access on this host: http://<host-address>[:<port>]";
• "Access URL: <access-url>";
• "Next: sign in to the console with the account above and change the initial password as prompted; if the platform security policy requires two-factor authentication, also bind two-factor authentication".

Difference between the two addresses:

Procedure

1. Immediately store the initial password under the customer's password-management rules.
2. To view it again before the first password change, run on the install host:

# Install host · root · read-only (view the initial password)
sudo zenova root-password show

3. Open the Access URL in a browser, sign in, and complete first sign-in and initialization per Chapter 6. If it will not open, try Direct access on this host first.

Note: do not send the initial password over instant messaging, email, or a ticket, and do not record or screenshot it for anyone off the host. The initial password is also stored in /opt/zenova/.env.runtime/root-password-initial (mode 0600). After the first password change it is invalid, and root-password show is no longer available. If root forgets the password or every two-factor method is lost, reset with sudo zenova root-password set (section 8.7).

Note: after the completion output, complete the off-host backup of key material and the first platform backup per sections 8.1 and 8.2. Without those two, the platform cannot be recovered after a failure.

4.8 Interruption and resume

After confirm-install, the installer records each completed stage under /opt/zenova/state/. Rerunning the same install command skips completed stages and continues from the breakpoint.

Procedure

1. Find the failure reason: the on-screen prompt, or the install log.

# Install host · root · read-only
tail -n 100 /opt/zenova/state/install.log

2. Follow the reason.
3. Rerun the command that is identical to last time (same flags).

# Install host · root · write (continue the install from the breakpoint)
cd /root/zenova-install
sudo ./zenova install "$ZPKG"

What you will see

• Completed stages no longer show "Installing"; the installer starts from the unfinished stage.

Note: do not delete progress files under /opt/zenova/state/ (install.json and similar), and do not delete any directory under /opt/zenova or stop services by hand to "start over". After the progress files are gone, the installer cannot tell what is complete, and the site cannot resume and cannot be cleaned safely. To really start over, use wipe-and-reinstall on an environment that meets the conditions (preview with --fresh --dry-run first). Never write rm -rf, docker rm, systemctl, or similar cleanup commands by hand.

Note: flags on resume must match the first run, especially --install-dir, --log-dir, and --business-entry-port. Changing flags makes the installer treat it as another install or refuse to continue.

Capability notes

Previous: 3. Prepare the environment · Next: 5. Non-interactive installation