1. Four decisions that must be made before deploy

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

This chapter: once the installer starts writing, the product, deployment form, and most data-dependency choices cannot be changed. This chapter states those decisions and their effects in one place. After the reader fills in the confirmation table in section 1.6, later chapters have a single set of answers. The readers are the implementation engineer for this POC and the customer system administrator who must sign off.

1.1 Which product

The first step on the customizer site is choosing the product. It cannot be changed after installation.

Both products use the same installer and the same commands. The only difference is which capabilities the offline package carries. Switching to the other product requires a wipe-and-reinstall (Chapter 11), which deletes all existing data.

How to decide: if this engagement only verifies gateway capabilities (model access, keys and calls, routing and guardrails, usage and audit), choose Zentrix Gateway. If knowledge bases, document parsing, and agents must be verified as well, choose the full edition. When unsure, choose the full edition. Capabilities not enabled stay in the offline package and can be turned on from the console after install, without downloading again.

Note: the offline-package file name contains a product field (zenova-zentrix_gateway-… or zenova-zenova-…); the installer file name does not. For the same version, the two products download installer files with the same name. Store them in separate directories after download, or it is easy to upload the wrong one.

1.2 Which form

This release provides two forms. They apply to completely different situations.

Single-host plus a remote gateway node (when business calls need to enter from another network zone) is in Chapter 9.

Note: every acceptance, backup, upgrade, and troubleshooting command in this manual is for a bare-metal install. The Helm form has a different offline package, install method, and day-to-day operations. Do not mix them.

1.3 Host and capacity

The installer checks the host before writing anything. If a requirement is not met, it stops at that check.

Disk space is cumulative by selected component. The check is free space on the filesystem that holds the install directory (default /opt/zenova).

Three typical combinations:

Note: the table is the install-check threshold. It does not include business-data growth, logs, or local backups. Call volume is small during a POC, so prepare to the threshold. Reassess concurrency and retention before going into production.

Two behaviors when disk is short: without --install-dir, insufficient space blocks the install, prints diagnostic code HOST_DISK_LOW, and on Linux lists the three mounts with the most free space as alternatives. With --install-dir passed explicitly (including the default value /opt/zenova written out), insufficient space is only a warning and the install continues. Do not add --install-dir just to skip the check — after you add it, this check is only a hint.

1.4 Access URL and ports

The access URL is what browsers and callers use. The local listen port is the port on the install host that actually receives requests. The two can differ when a proxy, NAT, or TLS ingress sits in front.

Note: filling in https:// does not make this host serve HTTPS. Certificate and TLS termination must happen on the customer's load balancer or reverse proxy; what is forwarded to this host is still plaintext HTTP. Also, when the access URL is http://, the sign-in page does not offer passkeys, and two-factor authentication can use only an authenticator app.

The admin ingress (console) shares one port with the business ingress by default. To put the console on a separate port, pass --admin-entry-port. The business ingress carries model, MCP, and A2A calls and health checks. If that port is in use, installation stops and does not pick another port automatically. If the admin ingress port is in use, the installer advances to the next free port and says so.

Firewall: inbound traffic only needs the business-ingress port (and 443 when enabled). On Linux the installer opens only the business ingress and 443 automatically; it does not open a split-out admin ingress. ufw and nftables are not touched; operations must configure them.

1.5 Data dependencies

Each of the three data dependencies is chosen as Deployed by us or Use an existing service.

Judge the choice against these constraints:

POC recommendation: let the installer deploy all three. Backup, restore, and wipe-and-reinstall then close on this host, without waiting on the customer database administrator's window.

Cloud-database pitfall: a cloud “high-privilege account” is usually not a superuser (rolsuper is false), and the installer check refuses it. Before choosing existing PostgreSQL, confirm on the customer side that SELECT rolsuper FROM pg_roles WHERE rolname = current_user; returns t.

1.6 Deployment-parameter confirmation table

Fill in the table below before install and have the customer confirm it. Do not write passwords or keys on the table; record only where they are kept and who keeps them.

Note: this table is the single source for every later step. After initialization in Chapter 6, compare actual values with this table and record any mismatch in the handover notes. When the POC moves to production, this table is the first page of the handover pack.

Capability notes

---

Next: 2. Get install artifacts from the download site