> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/platform-development/onprem-operations.md). # Operations Essentials: Offline Installation, TLS, Backups, Monitoring, and Acceptance Operations for private cloud and on-premises deployments: offline (air-gap) installation, domains and TLS certificates, backup and restore, optional monitoring, and post-deployment acceptance, with ke This page covers five areas that customer IT teams and SI partners need to understand when planning and operating MaiAgent installed with the deployment package (in a private cloud or on premises). Each area lists key points and common pitfalls. Actual commands and expected outputs are documented in the installation manual included with the deployment package; contact your MaiAgent representative to obtain it. ## Offline (Air-Gap) Installation **Key points** * **When to use it**: Use offline installation whenever the host cannot connect directly to MaiAgent's download site and Hugging Face. Environments with allowlists, proxies, or access to only some resources also count as offline. * **Only one site visit is needed**: Before visiting the site, use an internet-connected workstation to download the deployment package, service images, and model weights according to the deployment configuration, and verify each file's checksum. On site, transfer the materials to the host, verify them, and then install. * **Material size**: In testing, the default features for a single-host Docker deployment required 12 images, totaling about 8.7 GB; enabling monitoring and alerts brought this to about 9.2 GB. Model weights are additional when running models on the host. * **Transferring materials to the site**: Connect the workstation to the customer's internal network and copy directly, or use USB. Format USB drives as exFAT or NTFS: the backend image is about 7.5 GB as a single file, which FAT32 cannot accommodate. {% hint style="warning" %} **Precautions** * Finalize the deployment configuration before the site visit. Changes to features, versions, or CPU architecture require different materials and another download on the workstation. Host-specific settings (such as the address users connect to) can be changed on site. * Distributed Docker: Place the materials on every host running Docker. * Offline Kubernetes installation requires additional materials (cluster components, Helm charts, and system packages for storage components). Configure domains in internal DNS; do not use domain services that rely on public DNS resolution. * The deployment configuration contains model service keys and is needed again for upgrades. Store it encrypted according to company policy. * Messenger, Instagram, and WhatsApp channels require Meta to call MaiAgent's API over the internet and cannot be used in offline environments. {% endhint %} ## Domains and TLS Certificates **Key points** * **Two connection methods**: Use an IP address plus port (no domain required), or a separate domain for each service (for example, API, console, and chat page). Kubernetes supports only the latter. For required ports, see [System Requirements: Ports](/tech/en/platform-development/system-requirements.md#ports). * **When users connect through another address** (such as a cloud host's public IP, a NAT external address, or a domain pointing to either), set the server address during installation to the address users actually connect to. Using the host's internal IP prevents external users from opening the console or uploading files. * **Installation automatically generates a self-signed certificate**, so browsers show a security warning on first access. To replace it with the customer's certificate, certificates issued by a public CA or an internal enterprise CA are both supported, in either `.pfx` or certificate file plus private key form. The conversion tool included in the deployment package checks whether the certificate and private key match, whether the certificate chain is complete, and the time until expiry. * **Replacing a certificate does not require reinstallation**. In testing, all API calls succeeded during the change, with no service interruption. {% hint style="warning" %} **Precautions** * The certificate's Subject Alternative Name (SAN) must include the address users connect to. If users connect by IP, the certificate must include that IP; public CAs generally do not issue certificates containing IP addresses. * In cloud and most NAT environments, the host cannot reach its own external address, causing all post-deployment acceptance test connections to time out. Add NAT rules on the host to route traffic destined for its own external address back to its internal address. * Internal enterprise CA: Add the root CA to the backend service's trust list, or verification fails when the backend connects to its own URL. The CA certificate must include the Key Usage field. * The system does not proactively notify you of certificate expiry. Add expiry checks to the customer's existing monitoring or schedules. * Restoring a backup also restores the website certificate from the time of that backup. * Kubernetes certificates are stored in the cluster. Contact MaiAgent first to use a certificate issued by an internal enterprise CA. Before replacing certificates in distributed Docker or Kubernetes, confirm the steps and schedule with your MaiAgent representative. {% endhint %} ## Backup and Restore **Key points** * The deployment package includes a backup script that backs up the database, object storage (uploaded files), search indexes, cache and message queue, reverse proxy configuration, and service settings (including each service's passwords and encryption keys) in one operation. * Backups are stored in a directory on the host by default and retained for 7 days. Both the directory and retention period are configurable; scheduled backups with cron are also supported. * Restoring stops services, overwrites data, and restarts services. The system is unavailable during this process. In testing (a new installation with very little data), backup took about 1 minute and restore about 2.5 minutes. * A backup is automatically created before upgrades and marked for retention. See [Versions and Upgrades: Rollback Limitations](/tech/en/platform-development/onprem-versioning-and-upgrades.md#rollback). {% hint style="danger" %} **Precautions** * The default backup directory is on the same disk as the system, so host failure can also destroy backups. Mount a separate disk or network storage as the backup directory. * If encryption keys in the service settings are lost, encrypted data cannot be decrypted. Do not delete or replace them. * Restore operations have ordering dependencies. Restore the entire backup, not just part of it. * Before production use, perform a restore drill: create a recognizable record, back up, delete it, restore, and confirm the record returns. * For distributed Docker, run the script on the deployment host; data from all hosts is stored centrally on that host. For Kubernetes, run it on the control node. If the cluster belongs to the customer (was not created by the installer), the built-in script cannot be used; use the cluster's existing backup mechanism. * Backup failures do not trigger monitoring alerts. Check scheduled backup results separately. {% endhint %} ## Monitoring (Optional) **Key points** * When enabled, deploys VictoriaMetrics (metrics, retained for 30 days by default), VictoriaLogs (logs, retained for 14 days by default), and Grafana dashboards covering hosts, containers, databases, cache, search engines, object storage, and message queues. If the host has NVIDIA drivers, GPU utilization, memory, and temperature are also collected. * Alerts have a separate switch: when enabled, built-in rules (such as high host CPU, memory, or disk usage) send Email notifications. Currently, notifications support only Email (SMTP). {% hint style="warning" %} **Precautions** * The following are currently outside monitoring coverage: application metrics (such as HTTP error rates and request latency), business metrics (such as conversation volume), external checks that users can connect, certificate expiry, and backup success. For external availability, use the customer's existing external monitoring to call the API URL. * Kubernetes monitoring interfaces have no external route; connect using port-forward. * Confirm monitoring and alert setup (thresholds and notification recipients) with MaiAgent before enabling them. {% endhint %} ## Post-Deployment Acceptance **Key points** * When automatic acceptance is selected in the deployment configuration (recommended), functional acceptance tests (deploy-test) run at the end of installation and generate HTML and JSON reports. They can also be run separately afterward, for example after a certificate change or upgrade. * **Passing criteria**: All tests in phase 0 (infrastructure) and phase 1 (smoke tests) must pass. Review failures from phase 2 onward individually. Skipped items are usually optional features that were not enabled; skipped or unverified items do not count as passing. * If the Deployment Configuration Confirmation Form was completed before deployment, use the verification tool generated with the form to compare the actual system configuration and confirm that all feature switches match the form. | # | Acceptance item | Passing condition | | - | --------------------------------------------- | -------------------------------------------------- | | 1 | Installation result | No failed steps | | 2 | Service status | All services are running | | 3 | Console, chat page, administration interface | All can be opened and logged into | | 4 | Default account password | Changed; the factory password can no longer log in | | 5 | Functional acceptance tests | All phase 0 and 1 tests pass | | 6 | Backup | Backup script runs successfully | | 7 | Form verification (if the form was completed) | No discrepancies | {% hint style="danger" %} **Precautions** * The default administrator account created by the deployment package uses a publicly known factory password. Change it immediately after installation and do not allow user connections until it has been changed. * After changing the acceptance test account password, also update the copy saved in the deployment directory, or subsequent acceptance tests will fail to log in. * Browser interaction tests require a separately delivered acceptance test image. Without it, the report marks these tests as unverified. * Services start automatically after a host reboot; in testing, login was available after about 1.5 minutes. {% endhint %} ## Email Settings for Invitations and Notifications The platform sends member management Email invitations, human handoff notifications, and similar messages through the customer's SMTP server. The deployment package does not include a mail server or configure outgoing mail during installation. After installation, a system administrator must enter the following in the Email settings of the **administration interface** (Django administration): * **SMTP server**: Host, port, username and password, and sender address. Without these settings, invitation emails are not sent. * **Registration page URL template**: The registration link in invitation emails. Use the console login URL with the invitation code parameter, for example `https://<後台網址>/login?invitationCode={invitationCode}`; `{invitationCode}` is replaced with the code for that invitation. The console URL is the address provided during installation for users to access the console (use `https://` when using a domain and TLS). Without this setting, invitation emails cannot be sent. {% hint style="info" %} * These two settings are shared system settings for the entire deployment. The organization console has no corresponding fields, so organization administrators cannot change them; contact the system administrator for adjustments. * Changing the registration page URL template affects only emails sent afterward. Previously sent invitations keep the old link; resend them from the invitation status in the console when needed. * This setting is unrelated to [Chat Platform Basic Settings: Custom Domain (CNAME)](https://docs.maiagent.ai/build/channels/basic-settings#custom-domain) in the user manual: custom domains affect only the chat page's public URL. {% endhint %} ### Which Emails Require Email Settings and the Registration Page URL The table below lists the system emails the platform sends on its own, and what happens for each when the email settings (the SMTP server above, or AWS SES) or the registration page URL template are not configured. For when each email is sent, who receives it, and whether it can be turned off, see [System Notifications and Email](https://docs.maiagent.ai/start/system-emails) in the user manual. | System email | Requires email settings | Requires registration page URL template | Without email settings | | ----------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Password reset email | Yes | No | A user who submits "Forgot password" on the login page sees an error and receives no email | | Invitation email | Yes | Yes: if empty, the invitation is marked as failed to send, and "Resend" also fails | The invitation is marked as failed to send | | Set-password email (bulk member import) | Yes | No | Members are still created, but no emails are sent for the entire batch and no sending records are kept | | Human handoff notification email | Yes | The conversation link in the email uses the registration page URL template: if empty, the link cannot be opened | No email is sent; the human handoff notification in the notification center is still issued | | Connector request email | Yes | No | No email is sent; the member's request is still submitted | | MCP tool requires re-authorization | Yes | No | No email is sent; only the notification center notification is issued | | Schedule skipped tools with expired authorization | Yes | No | No email is sent; the schedule's execution record still logs the skipped tools | | Low credit balance reminder, personal quota nearly exhausted/expiring | Yes | No | No email is sent; the notification center reminder is still issued | | Organization review approved/rejected, data about to be permanently purged | Yes | No | No email is sent | | Plan and Credits notifications (plan scheduled, plan in effect, monthly Credits granted, Credits top-up credited) | Yes | No | Disabled by default in private cloud and on-premises deployments, so they are not sent; once enabled, if email settings are missing, each email is recorded as failed, and after the settings are fixed you can resend it from the notification log in the administration interface | {% hint style="warning" %} * For connector request emails, MCP tool re-authorization emails, and emails about schedules skipping tools with expired authorization, the console link in the email currently always points to the cloud edition URL (`admin.maiagent.ai`). Recipients in private cloud and on-premises deployments should log in to their own console directly and handle the matter on the connector management or tools page, rather than clicking the link in the email. * When sending through SMTP or AWS SES, the **subject and email template** for invitation emails and set-password emails have no default values. Fill them in as well; otherwise the emails are sent without a subject or content. {% endhint %} ## Redirecting to a Specified URL After Logout In deployments using single sign-on (SSO) or embedding MaiAgent in a corporate portal, the console's built-in login page is usually unnecessary, and users have nowhere to go if they remain there after logout. The deployment configuration can specify a post-logout redirect URL, such as the corporate portal home page or the IdP's logout endpoint. **Behavior when configured** * All three cases redirect the entire page to this URL: explicit logout, logout due to inactivity timeout, and opening a console link directly while not logged in. * The redirect navigates the entire page; the browser's Back button does not return to the console login page. * When unset, the original behavior is retained: users return to MaiAgent's login page. **URL format** * Accepts a full URL beginning with `http://` or `https://`, or an internal site path beginning with a single `/`. * Other formats (such as `javascript:` or URLs beginning with `//`) are ignored and treated as unset. {% hint style="info" %} This is a deployment setting for the console frontend and applies to all organizations in the deployment. The organization console has no corresponding field. It can be configured during installation; to add or change it afterward, contact your MaiAgent representative to arrange application. It takes effect after the frontend service reloads its configuration. For IdP behavior on logout by SSO type, see [Third-Party Login: Logout Behavior](https://docs.maiagent.ai/org/sso#logout-behavior) in the user manual. {% endhint %} ## Related Pages * [Deployment Types and Feature Comparison](/tech/en/platform-development/onprem-deployment-types.md) * [System Requirements](/tech/en/platform-development/system-requirements.md) * [Versions and Upgrades](/tech/en/platform-development/onprem-versioning-and-upgrades.md) * [Connecting On-Premises Model Services](/tech/en/platform-development/onprem-model-services.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/tech/en/platform-development/onprem-operations.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.