Deployment Guide

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)

# 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):

./dev/start-docker --china

Environment variable management

# 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

# 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
.\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

# 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

Getting Started

Core Features

Developers

Use Cases

Comparison of deployment methods

System requirements (privatized deployment)

Open Source Edition Deployment — Quick Start

Warehouse structure

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

Mainland China network acceleration

Environment variable management

macOS/Linux — Source code development model

Windows Deployment

Default service address

Kubernetes deployment

​Comparison of deployment methods

​System requirements (privatized deployment)

​Open Source Edition Deployment — Quick Start

​Warehouse structure

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

​Mainland China network acceleration

​Environment variable management

​macOS/Linux — Source code development model

​Windows Deployment

​Default service address

​Kubernetes deployment

Comparison of deployment methods

System requirements (privatized deployment)

Open Source Edition Deployment — Quick Start

Warehouse structure

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

Mainland China network acceleration

Environment variable management

macOS/Linux — Source code development model

Windows Deployment

Default service address

Kubernetes deployment