6. First sign-in and initialization

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

This chapter: a finished install only means the services are running. This chapter walks through every action from the first sign-in until the platform can be handed to the business side: change the root initial password and set up two-factor authentication per the customer's security requirements, check platform status, create the first tenant, import the license offline, finish operations notifications, and finally compare every planned value in the Chapter 1 confirmation table with the values on site. The reader is the implementation engineer. License import in section 6.4 needs the customer's tenant administrator as well.

6.1 Change the initial password and set up two-factor authentication

Prerequisite: you have the access URL printed at the end of install, the Direct access on this host URL, and the root initial password (32 random characters); you have confirmed with the customer whether platform accounts (root included) must use two-factor authentication.

On a fresh install the platform scope does not require two-factor authentication by default: after root changes the initial password, root goes straight to the platform admin console. When the customer requires two-factor authentication for platform accounts, finish steps 1–4 and continue with steps 5–7.

Procedure

1. On an office terminal that can reach the install host, open the Access URL in a browser. If it will not open, use the Direct access on this host URL instead. If direct access opens and the access URL does not, the problem is the front proxy, NAT, or load balancer. If neither opens, the problem is this host; troubleshoot per Chapter 12.
2. Sign in with account root and the initial password.
3. The page enters Change your initial password. Enter a new password that meets the rules listed on the page, then click Change and continue.
4. Enter the platform admin console. When the customer does not require two-factor authentication, this section is complete here.
5. In personal settings under Account security, bind two-factor authentication. Choose one method:
   • Authenticator app: scan the QR code on the page with an authenticator app on the phone, then enter the 6-digit code the app shows to finish binding. When using an authenticator app, the page gives a set of recovery codes; copy or print them and store them offline.
   • Passkey: follow the browser prompt and register with a security key on this machine or the system's biometrics.
6. Sign out, then sign in again with the new password and two-factor authentication.
7. Open Platform Accounts & Sign-in › Sign-in sessions, click Security policy, turn on Require two-step verification, and save. After that, a platform account that has not bound two-factor authentication must bind it at its next sign-in.

What you will see

• Step 3 states "Your current password is an initial or reset password. Change it before continuing."
• When the access URL starts with http://, step 5 has no passkey option; only an authenticator app can be used.
• In step 7, if this session did not pass two-factor authentication, save fails with "Bind two-factor authentication for yourself first, and sign in with two-factor authentication before turning this on". Finish steps 5–6 and try again.
• After root binds two-factor authentication, signing in with a password still requires two-factor authentication whether or not Require two-step verification is on, except on a valid trusted device. With an authenticator, enter the 6-digit code; when the authenticator is not at hand, choose Use a recovery code.

Note:

• Changing the password has a 10-minute limit. After timeout, sign in again and start over; no half-finished state is left behind. Once Require two-step verification is on, the Set up two-factor authentication step in the sign-in flow also has a 10-minute limit.
• After the password change, sudo zenova root-password show on the install host can no longer show the password, and the initial password in /opt/zenova/.env.runtime/root-password-initial is invalid at the same time.
• Each recovery code can be used once. Keep them separate from the authenticator app. Do not store a screenshot on the same phone, and do not send the new password or recovery codes over instant messaging, email, or a ticket.
• If root forgets the password, or both the authenticator and the recovery codes are lost, run sudo zenova root-password set on the install host. That command generates a new random password, clears two-factor authentication and recovery codes, invalidates every existing session, and writes an audit record. Then redo this section with the new password.

6.2 Check platform status

Applies to: after section 6.1 and before creating a tenant, confirm that status in the console matches the installer output.

Procedure

1. Open Gateway › Nodes and find the central gateway node office-primary.
2. Open System maintenance › Deployment configuration and inspect Latest acceptance.
3. On the same page check each deployment-configuration group: Access URL, Object storage, Operations notification channel, Ingress listen, Data dependencies.
4. Open System maintenance › System Updates and check the current version and each capability's state.

What you will see

Note:

• The Latest acceptance page has a Run acceptance button. After a problem is fixed you can trigger it again from the console; you do not need to rerun the install command.
• Before there is a tenant and model routing, the readiness check on the central gateway-node data plane returns 503 with reason no_tenant_routes. That is expected; it recovers after a tenant is created and models are configured.
• Console status matches the command line. To keep a copy, run sudo zenova status on the install host.

6.3 Create the first tenant

Applies to: after platform status checks out, create the tenant the customer will use and its default administrator.

Prerequisite: the customer has confirmed the tenant name, organization slug, default administrator, and settlement currency.

Procedure

1. Sign in to the platform admin console as root, open Tenants, and click Create Tenant.
2. Fill in four items:

3. Click Create.
4. Give the default administrator's email and initial password to the tenant administrator in person through a channel the customer accepts. Do not send them in plaintext over instant messaging, email, or a ticket.

What you will see

• A notice that "<tenant-name> has been created (admin: <email>)". The tenant appears in the list, status active.

Note:

• Settlement currency cannot be changed after creation. Confirm it with the customer before creating; a wrong choice cannot be corrected on the page. When settlement currency differs from the platform billing currency, the page asks for a summary exchange rate.
• root is only for platform-level settings (gateway nodes, deployment configuration, System Updates, tenant management, and similar). Do not use it as a day-to-day business account. Business configuration such as model providers, models, model groups, members, and API keys is done inside the tenant by the tenant administrator.
• When the tenant administrator signs in for the first time, change the initial password as the page requires; when the unit's security policy has Require two-step verification on, also bind two-factor authentication (authenticator app or passkey) as the page requires.

6.4 Import the license

Applies to: the delivery scope includes capabilities gated by the license. The license is imported by the tenant administrator. root does not see the License tab on the platform admin console.

Prerequisite: section 6.3 has created a tenant; the tenant administrator has finished first sign-in; the customer has decided the medium or channel used to send files out and bring them back (for example an approved removable drive, or an intranet file-exchange system).

The whole process has three steps: export a license request → send it to the vendor in exchange for a signed .lic file → import. The install host never needs the public network, and the database is never accessed.

Procedure

1. Export the license request. The tenant administrator signs in to the console from an office terminal, opens System Settings › Global settings › License, and clicks Export license request (.json). The browser downloads the request file to the office terminal.
2. Compute the digest of the request file on the office terminal and record it, so the other party can confirm the file was not changed in transit:

# Office terminal · ordinary user · read-only (Linux / macOS; on Windows use certutil -hashfile <file> SHA256)
sha256sum <license-request-file>.json

3. Send the request file out. Follow the customer's data-egress process: copy the request file and digest onto a machine that can reach the internet, then send them through the channel agreed with the vendor. The request file contains only binding information for the tenant and this deployment; it contains no passwords, keys, or business data.
4. Exchange it for a signed license. The vendor returns a .lic file; also ask them for that file's SHA-256 digest.
5. Bring the .lic file back. Follow the customer's data-import process: copy the .lic file back to an office terminal that can reach the console, compute the digest, and compare it with the digest the vendor gave:

# Office terminal · ordinary user · read-only
sha256sum <license-file>.lic

6. Import. The tenant administrator returns to System Settings › Global settings › License, clicks Import .lic file, and selects that file.
7. Open System maintenance › System Updates (or ask root to look) and confirm that capabilities previously shown as not included in the license are available again.

What you will see

• A successful import reports License imported. After validation it takes effect immediately; no service restart is needed.
• License source on the License tab changes from Community edition (no license imported) to Commercial license imported, and shows issued-to, license ID, and imported-at.
• A failed import reports License import failed. Common causes are the file being changed in transit, or the license not matching this tenant or this deployment. Recheck the digest and bring the file back again, or export a new license request and apply again.

Note:

• The license is bound to the tenant and this deployment. Importing it into another tenant, or onto another deployment, will not pass.
• Wipe-and-reinstall (Chapter 11) generates a new deployment identity. The previous license then becomes invalid; export a request and apply again per this section.
• Remove license on the page returns the deployment to having no imported license. Do not click it by mistake.
• A capability not covered by the license shows on System Updates that the license does not include this capability. That is a license-content check, not an install problem. Do not reinstall for it.

6.5 Finish operations notifications

Applies to: operations notifications were skipped at install and are added now; or an existing channel has not passed verification and needs to be corrected.

Prerequisite: the customer has created a DingTalk, Feishu, or WeCom group robot that will receive alerts, or has provided a webhook receive URL; the install host can reach that address.

Procedure

1. Sign in as root, open System maintenance › Deployment configuration, and find the Operations notification channel group.
2. Click Edit, fill in the channel address, and save.
3. Send a test message.
4. Ask the customer's alert recipient to confirm the test message in the matching group or receiver, and record the recipient's name and confirmation time in the handover notes.
5. When emergency notifications are needed, create a new DingTalk, Feishu, WeCom, or webhook channel on the console Notification channels page, with a different receiver from the channel in the previous step. After subscribing to Alerts, set Receive level to Emergency, send a test message, and Confirm received. When the control plane is unreachable or alert evaluation stops, gateway nodes send notifications to that channel directly.
6. On the same page, under Latest acceptance, click Run acceptance and confirm that Real egress and Ops channel binding are Pass.

What you will see

• After save it reports that the change was saved and related services will reload automatically, then that the change has taken effect.
• When the test message arrives it reports that the test message was delivered; on failure it reports that delivery failed.
• After re-running acceptance, both checks show Pass.

Note:

• Email is not provided as an operations-notification channel.
• When test-message delivery fails, first run sudo zenova doctor --target <channel-address> on the install host for layered DNS, TCP, TLS, and HTTP connectivity. When the report notes "direct connect; may not match production egress", the result does not represent connectivity of the gateway egress.
• "Send succeeded" is not enough. The recipient must confirm receipt before you can say alerts actually reach a person.
• When the emergency-notification channel uses the same receiver as other alert channels, the console Notification channels page shows a hint at the top. If the control plane is unreachable, both kinds of notification land in the same group and on-call staff cannot tell them apart.
• Which fields each channel shows on the page, and where the test button sits, follow the actual page.

6.6 Checklist after initialization

Compare every planned value in the confirmation table in Chapter 1 section 1.6 with the values on site. For any mismatch, either correct the site or, after the customer confirms, change the planned value, and record it in the handover notes.

# Install host · root · read-only (status snapshot to attach when checking)
sudo zenova status
sudo zenova backup list
chronyc tracking

Note: after this table is checked and the customer has signed, file it with the Chapter 1 confirmation table and a copy of the answers file (no passwords) as handover materials. Then complete model-provider access and real-call acceptance per Chapter 7.

Capability notes

Previous: 5. Non-interactive installation · Next: 7. Installation acceptance