Zentrix Gateway Deployment and Service Selection Guide

Download PDF · Downloads

2026.10 · This guide is for solution design and handover. Installer commands, component versions, and resource settings follow the installer, offline package, and implementation notes delivered for that engagement.

For the step-by-step procedure from downloading the installer through environment preparation, installation, initialization, and acceptance, see the Zentrix Gateway POC Deployment Manual (Read online).

1. Decide the operating model

Zentrix Gateway provides unified model and tool access and governance for business systems, developer tools, and external agents.

Product scope and deployment mode are decided separately. The same access-and-governance need can be met as a hosted SaaS service or deployed in an environment the enterprise operates. Where external models and tools run is a further, independent decision.

As a neutral third-party access and governance layer, the product supports combining different vendors and enterprise private models. Whether a given modality, protocol, or tool parameter is supported must be checked with real samples. A single entry point does not mean every upstream is equivalent.

2. Three common combinations

“Supports SaaS services” covers both offering the product as SaaS and connecting external SaaS models and tools. The two can stand independently: a private deployment can still call cloud tools, and a SaaS service still needs a defined connection scope.

Schematic. Whether data leaves the enterprise boundary depends on the whole combination, not only on where the gateway is installed.

3. Turning “no public cloud” into an acceptable plan

Staying off the public cloud can be a private-deployment goal, but every dependency must be pinned to an allowed network and resource location.

Boundaries of an offline environment:

• Installation does not need the public network. Everything required to install is in the installer and the offline package. The offline package and the answers file do not contain credentials. Credentials are entered on site from a secrets file or the terminal. After installation, the tenant administrator imports the license, which is verified locally.
• Upgrade packages, component packages, and extension packages are always downloaded by the delivery staff from the download site on a computer with internet access, then uploaded on site to the System Updates page or applied from the command line. The platform does not fetch them online.
• Automatic issuance of ingress certificates requires the control plane to reach the certificate authority and the DNS-provider API. When egress is not allowed, upload a wildcard certificate that covers the ingress domain.

At acceptance, check configuration against live connections and record allowed targets and business samples. When a disconnected-network test is required, run the named functions in an approved test environment. After public-network access is cut, public models, tools, and identity that depend on the internet becoming unavailable is a plan difference and must be written into the acceptance record.

When external SaaS is used, prompts, file fragments, tool arguments, and receipts sent upstream may contain business information. Agree authorization scope, data classification, and redaction requirements before making the calls.

4. SaaS onboarding and responsibilities

In the SaaS model the service provider operates the platform infrastructure, including installation, upgrades, backup and restore, ingress and certificates, gateway nodes, and tenant provisioning. The enterprise, as a tenant, manages its own members, permissions, model or tool authorization, and business-use policy. Concrete responsibility follows the service agreement.

1. Decide product scope, hosting region, how the tenant and the default administrator account are provisioned, and the billing currency of the tenant (it cannot be changed after creation).
2. Decide who purchases and maintains models, tools, and external subscriptions, and tenant quotas such as the monthly token cap.
3. The tenant administrator imports the license and configures administrative roles, members, SSO, and available capabilities.
4. For one business case, verify a successful call, a permission denial, billing attribution, and problem records.
5. Agree upgrade notices, incident response, backup and restore, data export, and handling after service stop. The service operator can export all data for that tenant asynchronously from tenant management.

Multi-tenant, tenant-management, and registration capabilities in the code show that the software can take that form. They do not replace commercial confirmation of the current SaaS plan, service region, or service level.

5. Private deployment and implementation preparation

5.1 Delivery form

The private-deployment form is chosen at install time. Only the three values below are valid. An unknown value makes startup and database migration fail immediately:

Install, upgrade, and backup/restore are performed only by the zenova program. The console pages System Updates and Backup & Restore call the same executor as the command line. The earlier Docker Compose offline package is no longer provided.

The delivery scope of the Kubernetes form, including tenant traffic ingress, follows the current implementation notes. Confirm with the implementation team before selecting it.

5.2 Deliverables

After it starts, the installer checks the sha256 and size of each component against the release manifest to confirm the media are complete.

Optional capabilities for the Zentrix Gateway edition (install answer edition = "zentrix_gateway") are listed below. Hosted agents and document parsing are not provided in the Zentrix Gateway edition.

Semantic cache is not a separately installed capability. It ships with core. After the tenant selects a semantic-cache vector model and a rerank model in Default models, it is turned on per rule in routing rules. No model is deployed on the host. Deployments that use OceanBase as the platform database do not support semantic cache.

Capabilities not enabled this time stay on the host and can be turned on later from System Updates.

5.3 Host requirements and pre-install checks

The installer checks the host before writing any files and reports each item. Failed items include the reason and the remedy. After the remedy, press Enter to recheck.

Install and operations commands require root. Run them with sudo. The Zentrix Gateway edition has no container-run capability and does not require a container runtime at install time.

To preflight only, append --check-only. The installer reads the package, checks versions, selects capabilities, and checks the host, then exits without writing anything.

5.4 Data dependencies

Choose a deployment mode for the platform database (PostgreSQL), the analytics database (ClickHouse), and object storage, one by one. After installation, Deployment configuration → Data dependencies shows whether each item is Deployed by the platform or Existing service, and who operates it.

Notes:

• The analytics database is required in every deployment form. Call details, usage statistics, and policy hits are stored there. A single-host bare-metal install can deploy it with the platform or use an existing service. Pre-upgrade checks add an “analytics database (ClickHouse)” item. An install without an analytics database is blocked from upgrading. Follow the prompt and run zenova install --reconfigure to deploy one or to fill in an existing ClickHouse, then recheck.
• Bundled object storage applies only to single-host bare-metal installs. The installer creates separate buckets for platform data, gateway payload archives, and audit archives.
• When using an existing database, the connection may be plaintext, encrypted (verification delegated to the system trust store), or encrypted and verified with a specified CA certificate. The last two both verify the certificate and hostname; they differ only in CA source. Encryption is recommended in production. Existing S3-compatible storage has no separate encryption option; an address that starts with https:// is an encrypted connection.
• After credentials are entered and before the real install, the installer probes existing services: database login, account privileges, extensions and version, connection limit, macros and create-database rights, and object-storage read, write, and delete. The probe writes and then deletes a temporary object. It does not write business data.
• The object-storage mode cannot be changed online after install. Back up, reinstall with the new choice, then restore.
• Local backups do not include a platform database or S3-compatible storage that is an existing service. Those parts are protected by the database administrator and the storage administrator using their own backup mechanisms. The secret-service key directory /etc/zenova/secret-service/keys is included in host-level backup and is stored separately from the backup archive. Restoring onto a different host requires that directory.

5.5 Single-host installation

sudo ./zenova install ./<offline-package>.zpkg

Interactive installation proceeds in this order: verify the package, check the host, select capabilities, confirm prefilled configuration, complete configuration that was not prefilled (access URLs, deployment mode of each dependency, object storage, operations notification channels), enter credentials and probe dependencies, send a test operations notification, and confirm what will be installed. No files are written before confirmation. Typing q at any step leaves nothing on the host. After confirmation, the installer installs the data layer, the control plane (the local central gateway node starts with the control plane), and the selected capabilities, then runs post-install acceptance.

On completion it prints the console URL, username root, the initial password, and the acceptance result. Before the first login password change, run sudo zenova root-password show on the install host to view the initial password again. To reset root, run sudo zenova root-password set.

Non-interactive installation uses an answers file and a secrets file:

sudo ./zenova install ./<offline-package>.zpkg --answers answers.toml --secret-file secrets.toml --with core

On first Linux (systemd) install, the installer writes only the business-ingress HTTP port and 443 into the host firewall (firewalld or iptables). A split-out admin ingress port, ingress ports changed after install, and the firewall on macOS are opened by operations. Ports other than the ingress ports do not need to be reachable from outside the host. Operations should allow only the ingress ports through the host firewall or the network boundary.

Choose a persistent filesystem for the install and log directories. On Linux, /tmp, /var/tmp, /home, /root, /run/user, /usr, /etc, and /boot are not supported. The install volume must allow executing programs. The install root may contain only letters, digits, dots, underscores, hyphens, and slashes. Path configuration has no automatic move. A host still allows only one central install. Canonical logs reuse the native daily / 500 MiB rotation and 30-day retention. The system journal and the bounded capture buffer on macOS keep their native layout.

If installation is interrupted or a step fails, fix the cause and rerun the same install command. Completed steps are skipped. After installation, day-to-day configuration changes are made on the console Deployment configuration page or with zenova config set.

5.6 Multi-host installation

When the answers file contains a host inventory ([[hosts]], each row with address, role, and site), running zenova install on the control host starts a multi-host install. Host roles include control plane, gateway node, platform database, analytics database, and arbiter. The install directory on each host follows --install-dir on the control host for this run. A gateway-node host sets its install directory in the answers file with gateway_install_dir = "/data/zenova-node" (the node default if omitted). It must not fall inside the central install directory.

1. The installer lists the host plan and any gaps, such as too few hosts or sites for a role. When there is a gap, the only options are to go back and edit or to exit.
2. Confirm address, role, and site host by host, and enter the SSH login method (private-key file, local ssh-agent, or one-time password). Several hosts may share one set of login credentials.
3. Enter the control-plane virtual address. It must be a single private IP.
4. Before writing, the installer logs into each host for a read-only preflight (the remote side runs --check-only). Writing starts only when every host passes.
5. Hosts are installed in waves, with live progress. If a host fails, the prompt is Wave N · host · reason. After the fix, rerun zenova install. Completed waves are skipped.

SSH credentials stay in memory. The install report records only addresses and results.

--install-dir and --log-dir specified on the control host are passed to preflight and the real install on every role host. Changing the path changes the resume identity, so hosts completed on the old path cannot be skipped silently. Gateway-node hosts do not use the central install root: if --install-dir on the control host is not the default /opt/zenova, gateway nodes also install there; otherwise they install to the node default /opt/zenova-node. The SSH staging cache remains at /var/lib/zenova/install-stage. That filesystem still needs space for the installer and the offline package.

5.7 Wipe-and-reinstall and resume after failure

Upgrade:

• Node-package prefetch and site order: when the upgrade includes a gateway-node package, online nodes keep serving while they download the new node package (at most 4 at a time, with resumable downloads). Only after the download is complete and verified are nodes drained and switched one by one, with a 15-second grace period after draining before the package is replaced. Nodes roll one at a time in alphabetical order of site label; nodes with no site come last. If any node fails to upgrade, the rollout stops and the remaining nodes stay on the old version. A node with no progress for 15 minutes is treated as failed.
• Service interruption and progress: the “Service interruption” shown by zenova status and the console is the real interruption (from writes stopping to service recovery); records from before this version show “—”. Both the command line and the console show gateway-node progress (n of N done) and the time spent in each stage. After the upgrade package is uploaded, the command line and the console use the same submission path, and the target version's upgrade executor takes over the local upgrade service and finishes the upgrade. Only when the upgrade-service protocol is too old do you first run sudo ./zenova upgrade <upgrade-package>.zpkg with the program in the installer package.
• On the first upgrade to this version, nodes still upgrade under the old procedure; prefetch and site order take full effect from the second upgrade.

Wipe-and-reinstall applies only to a single-host bare-metal install whose platform database, analytics database, and object storage are all self-hosted on the machine. If an existing external database or object storage is in use, the installer refuses to wipe and does not clean those resources. Gateway-node installs, multi-host, and Kubernetes deployments do not use this flow. An earlier Docker install (install root /opt/lobsterpool) can be cleaned by this flow and then replaced with the current bare-metal install.

1. Use a standalone installer of the same version as the new offline package. Place the installer, offline package, answers file, and secrets file outside the old install root and business directories.
2. Run a read-only preview first: sudo ./zenova install ./<offline-package>.zpkg --fresh --dry-run. The preview lists the version, form, and cleanup scope of the old deployment. It does not stop services or delete data.
3. After checking the preview and scheduling a downtime window, run: sudo ./zenova install ./<offline-package>.zpkg --fresh --confirm-data-loss DELETE_EXISTING_DATA.
4. Before deleting old data, the installer verifies the new package component digests and sizes, installer and package version and platform, install answers, and selected capabilities. If any check fails, deletion does not start.
5. The installer stops the old services, cleans services, data paths, and exclusive resources that belong to that install, then installs the new package as a first-time install and runs post-install acceptance.

Wipe-and-reinstall does not back up automatically. The cleanup scope includes backups already on the host. To keep old data, back up first and move the archive outside the cleanup scope. Restore is possible only onto the same version, deployment form, and platform. A backup from an older version cannot be restored onto a newer install.

If interrupted: when the old deployment was cleaned successfully and the following install failed, fix the install error and run an ordinary install of the same package (without --fresh) to resume from the existing progress. When cleanup itself failed or was interrupted, inspect what remains and why it failed. Running --fresh again and confirming deletion means wiping local data once more.

5.8 Gateway nodes

The control-plane host is itself the central gateway node. To handle requests closer to other hosts, a platform administrator adds a node under Gateway → Nodes, generates a one-time install command, and runs it as root on the target host:

sudo ./zenova install node --package zenova-node.zpkg --control-plane <control-plane callback URL> --token <one-time token>

The page requires the control-plane callback URL to start with https://. The node host must be able to reach that URL. When the control plane uses a self-signed or internal CA, the command includes that CA. The install command is valid for 24 hours. After it expires, reissue it from the node detail page. While a node is disconnected from the control plane, request records are spooled locally on the node and uploaded after recovery. While the control plane is unavailable, the gateway node continues to serve with the last configuration it received. During a system upgrade, remote gateway nodes are updated one host at a time in the Gateway node rolling update phase. When adding a node, Install directory may be filled in (leave it empty to install to /opt/zenova-node). The node program, data, and configuration all live under that directory, and the command then includes --install-dir <directory>. Upgrades reuse the directory from the first install and cannot change it. Nodes from earlier versions that used /var/lib/zenova-node and /etc/zenova-node are migrated into the install directory on upgrade. Failure rolls the node back automatically.

5.9 Implementation preparation and go-live sequence

Prepare before implementation:

• Organization and identity: platform administrator, tenant administrator, and other administrative roles; SSO or local-account plan.
• Resources and network: host sizing, network segments, business and admin access URLs, ingress ports, TLS, DNS, and time sync.
• Models and tools: model sources, inference resources, account authorization, and allowed connection addresses.
• Delivery artifacts: installer, offline package, node package, and license matching architecture, version, and deployment form.
• Operations: off-host backup location, custody of the master key and the secret-service key directory, recovery target, operations notification channels, and maintenance windows.

Size platform services and model-inference resources separately. Host checks in the installer do not include GPU requirements. Compute for local models, embeddings, or other inference components is estimated from the actual plan.

Suggested go-live sequence: base environment → install and post-install acceptance → first login and platform accounts → ingress URLs and certificates → gateway nodes → tenants and licenses → organization and duties → models and tools → usage authorization and policies → ordinary-account verification → alerting, backup, and recovery rehearsal → business handover.

Passing post-install acceptance only shows that the base platform services are available. Model and tool authorization, traffic-rule rollout, real business cases, and recovery rehearsal still need to be completed item by item.

6. Operations responsibilities

When a host fails or the console is unavailable, the platform administrator runs sudo zenova status on the install host to see the status of each service, the current version, and the latest upgrade, then sudo zenova restart <service> as needed.

7. Handover and change

Before an upgrade or expansion, recheck version, capabilities, data and configuration changes, licenses, resources, and the maintenance window. Complete a backup and record the backup ID first, then follow the implementation steps for that engagement, and finally verify the critical business path and the denial path.

The neutral-third-party role preserves room to choose vendors and to govern them uniformly. Ongoing portability still requires maintained interface samples, a credential inventory, data export, and a replacement plan.