5. Non-interactive installation

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

This chapter: non-interactive install replaces the questions with an answers file (--answers) and a secrets file (--secret-file). The installer asks nothing, which suits batch deploy, remote execution, and unattended runs. This chapter lists every field in the two files, what happens when a field is wrong, and two complete examples you can copy and change. The reader is an implementation engineer who must finish install from a script or a remote session. For a single host with someone at the terminal, use the interactive install in Chapter 4.

5.1 When to use non-interactive install

Applies to: the same parameters will be installed on several hosts; you can run only through a remote session or an automation tool; nobody will be at the terminal to answer questions during install.

Non-interactive and interactive install follow the same flow, the same host checks, dependency probe, four install stages, and post-install acceptance. The only differences are where the answers come from and what happens when a problem appears. Interactive install stops so you can fix it on the spot. Non-interactive install reports the error and exits; you correct the files and rerun the same command.

Rules

Procedure

1. Write the answers file answers.toml per section 5.2.
2. When any dependency uses an existing service, write the secrets file secrets.toml per section 5.3 and set it to 0600. No secrets file is needed when the installer deploys all three dependencies.
3. Run preflight once with --check-only. After it passes, drop --check-only and run for real. Full commands are in sections 5.4 and 5.5.

What you will see

• Preflight passed prints "Preflight passed: nothing was written".
• The real run prints host-check results, dependency-probe results, notification-test results (if configured), the four install stages, and post-install acceptance, then the sign-in account and initial password (see Chapter 4 section 4.7).

Note: after an interruption or failure, fix the cause and rerun the same command. The installer continues from the breakpoint. On resume the answers-file contents must match the first run; otherwise it reports "answers do not match the last install; to change configuration, rerun with --reconfigure". A --with that differs from last time is also refused, with the difference listed. --reconfigure enters the questions and needs someone at the terminal.

5.2 Answers-file fields

The answers file is TOML. Top-level fields must be written before every [section] — a top-level field written after a section is treated as a member of that section and then reported as unrecognized.

Top-level fields

Two further optional top-level fields, rarely used in a POC: admin_public_url (admin access address; fill in only when the console has its own reverse proxy or domain; when blank it is derived from the access-URL host and the admin-ingress port) and otlp_endpoint (trace export address). Both must be valid http:// or https:// addresses.

[postgres] platform database

Write exactly one of the two forms below.

Fields inside external:

[clickhouse] analytics database (required)

Fields inside external:

[object_store] object storage

Write exactly one of the three forms below. It cannot be changed online after install.

Fields inside external_s3 (all four required):

[notify] operations-notification channel

To skip configuration, omit this section and write notify_skipped = true at the top of the answers file. Put the signing secret in the secrets file as notify_secret; do not write it into the answers file.

[[hosts]] host list

Do not write this section for a single-host install. Writing [[hosts]] enters a multi-host install. Each row has address, role (control_plane, gateway, postgres, clickhouse, arbiter), and site. A multi-host install must use existing S3-compatible storage; bundled or local_dir reports "a multi-replica deployment must use existing S3-compatible storage; bundled object storage or a local directory cannot be used". Multi-host install is out of scope for this manual.

Note: the answers file contains no passwords, keys, or license, and can be filed with the handover materials. After install, the answers actually used this run are saved at /opt/zenova/state/answers.toml.

5.3 Secrets file

The secrets file is also TOML. Fill in the keys required by the chosen dependencies and notification channel.

Procedure

1. In the install staging directory, create an empty file that only root can read and write. Do not use echo to write a password, so the password does not enter command history.

# Install host · root · write (create an empty secrets file, mode 0600)
cd /root/zenova-install
umask 077
touch secrets.toml
chmod 600 secrets.toml

2. Open secrets.toml in a text editor and write what is needed, for example:

pg_admin_password = "<PostgreSQL-superuser-password>"
ch_password = "<ClickHouse-account-password>"
s3_access_key_id = "<access-key-id>"
s3_access_key_secret = "<secret-access-key>"

3. Check mode and owner.

# Install host · root · read-only
ls -l /root/zenova-install/secrets.toml

What you will see

• The mode column is -rw-------, owner root.

Note: when a credential required by a dependency is missing, the installer reports "when using an existing service, non-interactive install must provide credentials with --secret-file" and stops on a failed dependency probe. It does not fall back to asking on the terminal. Wrong mode reports "secrets-file mode must be 0600: <path>". After install, delete the file per Chapter 8 section 8.3, or hand it over under the customer's credential-management rules.

5.4 Example 1: installer deploys all three dependencies

Applies to: the recommended POC combination. The platform database, analytics database, and object storage are all deployed by the installer on this host. No secrets file is needed.

Procedure

1. Write the answers file answers.toml in the install staging directory:

# Top-level fields before every section
public_url = "http://<host-address>"
[notify]
kind = "webhook"
target = "https://hooks.example.com/zentrix"

[postgres]
managed = {}

[clickhouse]
managed = {}

[object_store]
bundled = {}

2. Preflight (writes nothing):

# Install host · root · read-only (preflight; writes nothing)
cd /root/zenova-install
sudo ./zenova install ./<offline-package>.zpkg --answers answers.toml --with core --check-only </dev/null

3. After preflight passes, install for real:

# Install host · root · write (start install; no further questions)
cd /root/zenova-install
sudo ./zenova install ./<offline-package>.zpkg --answers answers.toml --with core </dev/null

</dev/null attaches standard input to the empty device. A non-interactive install does not ask questions in the normal case. If a step still needs input, the installer immediately reads end-of-input, treats it as typing q, and exits (exit code 130), instead of blocking forever in an unattended session. Always add it when calling from a remote session or an automation tool.

What you will see

• Preflight prints "Preflight passed: nothing was written".
• The real install completes the data layer, control plane, selected capabilities, and post-install acceptance in order; about 4 minutes on a clean host.
• Finally it prints time per stage, the acceptance result, the root account and initial password, Direct access on this host, and Access URL.

Note: --with must match the product of this offline package. Zentrix Gateway does not provide hosted agents or document parsing; including them reports "… does not include the "…" capability; remove it from --with". Capability IDs are core, knowledge_base, agent_runtime, doc_parse, ha_data.

5.5 Example 2: existing databases and object storage

Applies to: the customer requires the platform database, analytics database, and object storage all to be existing services, and the database connections must be encrypted.

Prerequisite: the existing services meet every requirement in Chapter 1 section 1.5 (PostgreSQL superuser and extensions, ClickHouse version and macros, a bucket created in advance with read/write/delete). If certificates are issued by an internal CA, the CA file is already on the install host.

Procedure

1. Place the CA certificate the customer provided in the install staging directory, for example /root/zenova-install/customer-ca.pem (it must be referenced by absolute path).
2. Write the answers file answers.toml:

public_url = "https://<access-domain>"
business_listen_port = 80

[postgres]
# When the certificate is issued by a public CA you may write tls = "required"
external = { host = "<PostgreSQL-address>", port = 5432, user = "<superuser-account>", tls = { verify_full = { ca_file = "/root/zenova-install/customer-ca.pem" } } }

[clickhouse]
external = { host = "<ClickHouse-address>", port = 8443, database = "zenova", user = "default", tls = { verify_full = { ca_file = "/root/zenova-install/customer-ca.pem" } } }

[object_store]
external_s3 = { endpoint = "https://<object-storage-address>", region = "<region>", bucket = "<bucket-name>", addressing = "path" }

[notify]
kind = "wecom"
target = "<WeCom-robot-address>"

Do not write database in [postgres]. When existing ClickHouse is replicated, add replicated = true inside external.

3. Create the secrets file secrets.toml (0600) per section 5.3 and write:

pg_admin_password = "<PostgreSQL-superuser-password>"
ch_password = "<ClickHouse-account-password>"
s3_access_key_id = "<access-key-id>"
s3_access_key_secret = "<secret-access-key>"

4. Preflight, then install for real:

# Install host · root · read-only (preflight; writes nothing)
cd /root/zenova-install
sudo ./zenova install ./<offline-package>.zpkg --answers answers.toml --secret-file secrets.toml --with core --check-only </dev/null

# Install host · root · write (start install; no further questions)
cd /root/zenova-install
sudo ./zenova install ./<offline-package>.zpkg --answers answers.toml --secret-file secrets.toml --with core </dev/null

Encryption-mode spellings

What you will see

• The dependency probe passes item by item: the PostgreSQL account can log in, is a superuser, and has the extensions; ClickHouse version, macros, and create-database rights are met; object storage read, write, and delete work. The probe creates and then deletes a temporary database or object; it does not write business data.
• The notification test shows "Test message sent; confirm it was received"; confirm receipt in the WeCom group.
• After that, same as example 1.

Note:

• When the dependency probe fails, the screen shows "dependency probe failed: <reason>, contact <owner>", for example needing the database administrator or storage administrator. After the fix, rerun the same command.
• When existing PostgreSQL already holds data for this platform, an ordinary install stops and tells you to use takeover (out of scope for this manual).
• This example's access URL is https://. The certificate is terminated by the customer's front load balancer or reverse proxy. business_listen_port is the port the TLS ingress forwards to on this host. This host does not serve HTTPS.
• With existing PostgreSQL and existing S3, zenova backup does not include those two parts; the corresponding administrators are responsible. This environment also does not support wipe-and-reinstall.

5.6 Turning download-site prefills into a non-interactive run

Applies to: the offline package was downloaded after filling in Prefilled settings on the download site, so it already carries a set of answers, and you now want to run non-interactively.

Prefills from the download site travel with the offline package. During interactive install, the installer lists those items for confirmation: ordinary items are confirmed with Enter; address-type items (existing-service addresses, notification-channel address) are marked "from the customizer site, unsigned" and need y one by one.

To switch to non-interactive:

Procedure

1. Write a complete answers.toml per section 5.2. You may copy the same prefills from the Configuration link on the download page (follow the actual page), but you must complete every required section — --answers is a whole-file replacement. Items prefilled in the offline package but missing from the answers file are not reused, and the installer reports "missing <item>".
2. Prepare a secrets file per section 5.3 when credentials are needed. The download site never collects credentials; this step cannot be skipped.
3. Run the commands in section 5.4 or 5.5, including --answers.

What you will see

• The installer no longer shows Confirm prefilled settings and does not require y one by one. It goes straight to the host check.

Note: --answers has the highest precedence. After it is given, prefills inside the offline package do not take part in this install. The answers file is provided by the implementation engineer and is treated as already confirmed, so check address-type fields with the customer before writing them (you can compare with the confirmation table in Chapter 1 section 1.6).

Capability notes

Previous: 4. Interactive installation · Next: 6. First sign-in and initialization