> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zgi.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment Guide

> From cloud trial to self-hosted production — choose the right deployment for you

## Comparison of deployment methods

| Method                            | Suitable scenario                                | Data location                 | Online time    |
| --------------------------------- | ------------------------------------------------ | ----------------------------- | -------------- |
| **Cloud SaaS**                    | Quick verification, small and medium-sized teams | ZGI Cloud (encrypted storage) | Ready to use   |
| **Docker Compose**                | Development environment, small-scale production  | Corporate intranet            | 1 hour         |
| **Kubernetes**                    | Production high availability                     | Enterprise intranet           | 30 minutes     |
| **Privatized Enterprise Edition** | Finance, government affairs, medical compliance  | Complete self-control         | 3 working days |

## System requirements (privatized deployment)

| Components       | Minimum Configuration | Recommended Configuration |
| ---------------- | --------------------- | ------------------------- |
| Operating System | Linux (Ubuntu 20.04+) | Ubuntu 22.04 LTS          |
| Processor        | 8 cores               | 16 cores+                 |
| Memory           | 16 GB                 | 32 GB+                    |
| Storage          | 100 GB SSD            | 500 GB SSD+               |
| Docker           | 20.10+                | Kubernetes 1.24+          |

## Open Source Edition Deployment — Quick Start

The ZGI core framework is completely open source on GitHub, and anyone can start the complete service stack directly from the source code.

### Warehouse structure

Use **git submodule** to organize multiple warehouses, and the top-level warehouse is responsible for product-level aggregation:

| Catalog          | Description                             | Warehouse address         |
| ---------------- | --------------------------------------- | ------------------------- |
| `api/`           | Backend service (Go)                    | `zgiai/zgi-api`           |
| `web/`           | Front-end application (React)           | `zgiai/zgi-web`           |
| `sandbox/`       | Code execution sandbox                  | `zgiai/zgi-sandbox`       |
| `plugin-runner/` | Plug-in execution service               | `zgiai/zgi-plugin-runner` |
| `docker/`        | Shared middleware and deployment assets | —                         |

### macOS/Linux — Docker one-click startup (recommended)

```shell theme={null}
# Clone repository
git clone https://github.com/zgiai/zgi.git
cd zgi

# Start the complete Docker stack with one click
make dev-docker
```

> **make dev-docker will be automatically completed when run for the first time**
>
> Initialize submodule → Copy missing env template → Regenerate root compose → Start full Docker stack. No manual work required.

### Mainland China network acceleration

If the image build is slow or unstable, you can use the `--china` mode to inject the recommended image source configuration (the template file will not be rewritten):

```shell theme={null}
./dev/start-docker --china
```

### Environment variable management

```shell theme={null}
# Check differences between local env and template
make env-check

# Append missing items (does not overwrite existing values)
make env-sync
```

### macOS/Linux — Source code development model

```shell theme={null}
# Initialize development environment
make setup

# Start middleware (database, cache, etc.)
make dev-docker

# Start the backend and frontend separately
make dev-api
make dev-web
```

### Windows Deployment

Minimum support for Windows is **Docker Desktop + PowerShell**. Source code development aids rely on Unix-like shells and are not available on Windows.

```powershell theme={null}
# PowerShell
.\dev\start-docker.ps1

# PowerShell (domestic mirror)
.\dev\start-docker.ps1 -china
```

### Default service address

| Services          | Address                  | Description               |
| ----------------- | ------------------------ | ------------------------- |
| **Web front-end** | `http://localhost:13000` | Console interface         |
| **API Backend**   | `http://localhost:2678`  | REST API                  |
| PostgreSQL        | `localhost:15432`        | Master database           |
| Redis             | `localhost:16379`        | Cache and message queue   |
| Weaviate          | `http://localhost:18080` | Vector database           |
| Neo4j HTTP        | `http://localhost:17474` | Knowledge Graph           |
| Sandbox           | `http://localhost:18194` | Code execution sandbox    |
| Plugin Runner     | `http://localhost:15000` | Plug-in execution service |

## Kubernetes deployment

```shell theme={null}
# Add ZGI Helm repository
helm repo add zgi https://charts.zgi.cn

# Install
helm install zgi zgi/zgi \
  --namespace zgi --create-namespace \
  --set global.storageClass=your-storage-class \
  --values values-production.yaml
```