One-Click Installation Guide

📘 Overview

This document describes how to quickly deploy a CSGHUB test environment using the one-click script. This method is mainly for functional verification, development testing, and proof-of-concept (PoC) scenarios.

⚠️ Important Note: This installation method is only suitable for test and development environments. For production, please use the standard deployment process.

🧩 System and Prerequisites

✅ Supported Operating Systems

System Type	Notes
Alpine Linux	Lightweight support, some features limited (e.g., GPU)
Ubuntu / Debian	Recommended
CentOS / RHEL / Rocky / Alma / Fedora	Compatible support

💻 Hardware Requirements

Resource Type	Minimum Configuration	Recommended Configuration
CPU	4 cores	8 cores
Memory	8 GB	16 GB
Storage	200 GB	500 GB
Network	Internet access	Static public IP preferred

🔧 Software Dependencies

bash: script execution
curl: download installation package
root privileges (required)

⚙️ One-Click Installation Command

# Replace example.com with your actual domain
curl -sfL http://quick-install.opencsg.com | bash -s -- --domain csghub.example.com

The script will automatically perform the following steps:

Detect system environment
Install lightweight K3s Kubernetes cluster
Automatically install Helm
Deploy the CSGHUB Helm Chart
Configure domain resolution and access entry
Output access information and login credentials

🧭 Installation Flow Overview

1️⃣ Environment Detection and Dependency Installation

The script automatically:

Checks the operating system type
Updates system package repositories
Installs basic dependencies (bash, curl, jq, iproute2, gettext, gnupg2, etc.)
Automatically installs Helm if not present

2️⃣ K3S Cluster Deployment

Installs K3s using the official script (version v1.30.4+k3s1)
Configures local registry and image acceleration
Detects network interfaces and sets cluster communication interface
Waits until K3s nodes are Ready

3️⃣ NVIDIA GPU Support (Optional)

If --enable-gpu is enabled:

Installs NVIDIA Container Toolkit
Configures containerd GPU runtime
Deploys nvidia-device-plugin automatically
Labels nodes with GPU capability and model

⚠️ GPU is not supported on Alpine.

Requirements:

NVIDIA driver ≥ 384.81

CUDA ≥ 12.1

4️⃣ Deploy CSGHUB Core Components

Adds and updates Helm repositories automatically
Creates csghub namespace
Installs or upgrades csghub Helm Chart
Configures envoyGateway and Kourier service types
Automatically generates login info into login.txt

5️⃣ Network and Domain Configuration

If --hosts-alias is enabled (default):
- Automatically register domain in /etc/hosts
  - Updates CoreDNS ConfigMap for local domain resolution
    - Domains include:
      - csghub.{domain}
        
        casdoor.{domain}
        
        minio.{domain}
        
        *.csghub.{domain}
        
        csgship.{domain}
        
        if csgship enabled
        
        csgship-api.{domain}
        
        if csgship enabled

6️⃣ Private Registry Configuration

After installation, the script automatically:

Retrieves the csghub-docker-credential Secret
Updates /etc/rancher/k3s/registries.yaml
Restarts K3s to apply new private image registry configuration

⚡ Parameters Configuration

Required

Parameter	Description	Default Value
`--domain <domain>`	Access domain for deployment (required)

Optional

Parameter	Description	Default Value
`--data <data_dir>`	Custom data directory for K3S and components	`/var/lib/rancher`
`--enable-gpu`	Enable NVIDIA GPU support	`false`
`--enable-nfs-pv`	Enable NFS PV provisioner	`true`
`--edition`	【Deprecated】Specify edition type	`ee`
`--install-cn`	Use China mirror sources	`false`
`--hosts-alias`	Enable local hosts domain resolution	`true`
`--extra-args "<args1> <args2>"`	Additional Helm Chart arguments
`--dry-run`	Print commands without executing	`false`
`--verbose`	Print detailed logs	`false`
`--ghproxy <url>`	Set GitHub proxy URL	https://ghfast.top
`--interface <iface>`	Specify network interface	First system network card
`--timeout <seconds>`	Custom wait for resource timeouts in seconds	Default 300s
`--k3s-server <server_url>`	Specify the Master node URL when creating the AGENT node	Specifying this parameter will identify the added node as an Agent node
`--k3s-token <server_token>`	Specify the Master node token used when creating the AGENT node.	By default, the token is stored in /var/lib/rancher/k3s/server/token.
`--k3s-version <version>`	Specify the Kubernetes version for creating the AGENT node.	By default v1.34.3+k3s1

Notes：

【Deprecated】The parameters are passed in via --extra-args, and the default values for the above parameters are already provided by the following built-in parameters:
```
HELM_EXTRA_ARGS+=(--set global.edition='ee')
HELM_EXTRA_ARGS+=(--set global.gateway.service.type=NodePort)
```
You can override the above default configuration or add more configurations using the following definitions:
```
curl -sfL http://quick-install.opencsg.com | bash -s -- --domain csghub.example.com --extra-args "--set global.edition='ce'"
```
When adding an Agent node, the command used to execute the script repeatedly must be consistent, i.e., it must carry all options.

🌏 Common Installation Modes

1️⃣ Domestic Network Environment

curl -sfL http://quick-install.opencsg.com | bash -s -- --domain csghub.example.com --install-cn

Uses Alibaba Cloud mirror for faster downloads

2️⃣ Enable GPU Support

curl -sfL http://quick-install.opencsg.com | bash -s -- --domain csghub.example.com --enable-gpu

Installs NVIDIA driver dependencies and runtime automatically
Launches nvidia-device-plugin
Labels nodes with GPU capability

3️⃣ Enable Enterprise Features (CSGShip)

curl -sfL http://quick-install.opencsg.com | bash -s -- --domain csghub.example.com --extra-args "--set csgship.enabled='true'"

4️⃣ Expose Services via LoadBalancer

curl -sfL http://quick-install.opencsg.com | bash -s -- --domain csghub.example.com --extra-args "--set global.gateway.service.type=='NodePort'"

⚠️ Note: LoadBalancer mode will occupy port 22 automatically; change local SSH port to avoid conflict.

5️⃣ Combined Example

curl -sfL http://quick-install.opencsg.com | bash -s -- \
  --domain csghub.example.com \
  --enable-gpu \
  --install-cn \
  --extra-args "--set csgship.enabled='true' --set global.gateway.service.type=='NodePort'"

📋 Installation Verification and Access

Check Installation Status

kubectl get nodes
kubectl get pods -A
kubectl get svc -n csghub
kubectl get gc
kubectl get gtw -n csghub
kubectl get httproutes -n csghub

View Installation Logs

cat ./quick-install.log

View Access Information

cat ./login.txt

Includes:

CSGHUB login URL
Admin account and password
Key service endpoints

🧰 Troubleshooting

Issue 1: Script execution fails

curl -sfL http://quick-install.opencsg.com -o quick-install.sh
bash quick-install.sh --domain csghub.example.com

Issue 2: Domain cannot resolve

echo "$(hostname -I | awk '{print $1}') csghub.example.com" >> /etc/hosts

Issue 3: Port conflict

netstat -tulpn | grep :22

Issue 4: Error on line 138: Command [bash -c “$cmd”]

If the script shows this error along with [WARN] Retry, just wait the script will retry automatically.

View K3s and Pod Logs

sudo journalctl -u k3s -f
kubectl logs -n csghub -l app=csghub

🧹 Environment Cleanup

# Uninstall CSGHUB
helm uninstall csghub -n csghub

# Uninstall K3s (use with caution)
/usr/local/bin/k3s-uninstall.sh

# Remove residual data
rm -rf /var/lib/rancher /opt/csghub ~/.kube ~/.helm

✅ Recommended Post-Installation Steps

Verify all services are running properly
Backup admin login credentials

📘 Overview​

🧩 System and Prerequisites​

✅ Supported Operating Systems​

🔧 Software Dependencies​

⚙️ One-Click Installation Command​

🧭 Installation Flow Overview​

1️⃣ Environment Detection and Dependency Installation​

2️⃣ K3S Cluster Deployment​

3️⃣ NVIDIA GPU Support (Optional)​

4️⃣ Deploy CSGHUB Core Components​

5️⃣ Network and Domain Configuration​

6️⃣ Private Registry Configuration​

⚡ Parameters Configuration​

Required​

Optional​

🌏 Common Installation Modes​

1️⃣ Domestic Network Environment​

2️⃣ Enable GPU Support​

3️⃣ Enable Enterprise Features (CSGShip)​

4️⃣ Expose Services via LoadBalancer​

5️⃣ Combined Example​

📋 Installation Verification and Access​

Check Installation Status​

View Access Information​

🧰 Troubleshooting​

Issue 1: Script execution fails​

Issue 2: Domain cannot resolve​

Issue 3: Port conflict​

Issue 4: Error on line 138: Command [bash -c “$cmd”]​

View K3s and Pod Logs​

🧹 Environment Cleanup​

✅ Recommended Post-Installation Steps​