CSGShip Deployment Guide

📘 Overview

CSGShip is the backend service of the smart coding assistant in the CSGHub platform, providing CodeSouler (IDE plugin) with capabilities such as intelligent code completion, semantic search, conversational programming, AI code generation, and knowledge retrieval.

This component is deployed as an independent service, can scale compute nodes individually, supports horizontal scaling, and works in coordination with the main service (CSGHUB Server).

---

⚙️ System Requirements

Resource	Minimum	Recommended
CPU / Memory	4C / 8 GB	8C / 16 GB
Disk Space	10 GB	50 GB+
Supported Architectures	AMD64 / ARM64	Multi-architecture deployment

Software Dependencies

Component	Version	Notes
Kubernetes	1.28+	Cluster environment
Helm	3.12+	Chart management tool
PostgreSQL / Redis	Optional	External managed services can be used

---

🧩 Installation Steps

1️⃣ Add Helm Repository

helm repo add csghub https://charts.opencsg.com/csghub
helm repo update

2️⃣ Create Namespace (Optional)

kubectl create namespace csghub

3️⃣ Install CSGShip

Obtain the following information from the CSGHub main service:

• domain

  Provide a subdomain to expose the runner service.

  If your domain is example.com, the service will be exposed at runner.example.com.

• externalUrl

  helm get notes csghub -n csghub | grep -A 6 'Access your CSGHub'

​ Retrieves the external URL of CSGHub.

• hubAPIToken

  kubectl get cm csghub-core -o yaml -n csghub | grep 'API_TOKEN' | awk '{print $NF}'

• nats credentials

  kubectl get secret -n csghub csghub-nats \
      -o jsonpath='{.data.NATS_USERNAME}' | base64 -d && \
    echo -n " / " && \
    kubectl get secret -n csghub csghub-nats \
      -o jsonpath='{.data.NATS_PASSWORD}' | base64 -d

  • The above command outputs user and password.
  • host currently only supports the service name (i.e., deployed in the same cluster as CSGHub).
  • port is fixed at 4222.

  Example installation command:

  💡 Tip:

  • Domestic deployment:
    • --set global.image.registry="opencsg-registry.cn-beijing.cr.aliyuncs.com"
    • --set global.imageRegistry="opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq"

  💡 Tip: For long-term management, it’s recommended to save custom configurations in a custom-values.yaml file.

  helm install csgship csghub/csgship \
    --namespace csghub \
    --create-namespace \
    --set global.gateway.external.domain="example.com" \
    --set externalUrl="<csghub externalUrl>" \
    --set hubAPIToken="<csghub hub_api_token>" \
    --set billing.nats.host="<csghub nats service>" \
    --set billing.nats.port=4222 \
    --set billing.nats.user="<csghub nats username>" \
    --set billing.nats.password="<csghub nats password>"

Access URLs Example

Service	URL	Notes
CSGShip Frontend	http://csgship.example.com	OAuth configuration required (see below)
CSGShip API	http://csgship-api.example.com

---

⚙️ Values.yaml Configuration Reference

🌍 Global Settings (global)

Parameter	Default	Description
global.edition	ee	Edition type: ce (Community) / ee (Enterprise)
global.gateway.external.domain	example.com	Domain for platform access
global.gateway.tls.enabled	false	Enable HTTPS / TLS
global.persistence.size	10Gi	Default persistent volume size
global.postgresql.enabled	true	Enable built-in PostgreSQL
global.redis.enabled	true	Enable built-in Redis
global.chartContext.isBuiltIn	false	Whether deployed as subchart

🚢 CSGShip Service Settings

Parameter	Default	Description
externalUrl	https://csghub.example.com	URL of the CSGHub main service
image.repository	opencsghq/csgship	Main image repository
image.pullPolicy	IfNotPresent	Image pull policy

🔐 OAuth Login Configuration

CSGShip supports GitLab OAuth login. Set in values.yaml or via command line:

web:
  oauth:
    issuer: "https://gitlab.example.com"
    clientId: "<your-client-id>"
    clientSecret: "<your-client-secret>"

---

🗄️ Data Storage Configuration

PostgreSQL

Parameter	Default	Description
global.postgresql.enabled	true	Enable built-in database
global.postgresql.external.host	N/A	External DB host address
global.postgresql.external.port	5432	External DB port
global.postgresql.external.user	csghub	Username
global.postgresql.external.password	“”	Password
global.postgresql.external.sslmode	prefer	SSL mode

Example for production with external DB:

global:
  postgresql:
    enabled: false
    external:
      host: "pg.example.com"
      port: 5432
      user: "csghub"
      password: "StrongPassword"

Redis

Parameter	Default	Description
global.redis.enabled	true	Enable built-in Redis
global.redis.external.host	N/A	External Redis host
global.redis.external.port	6379	External Redis port
global.redis.external.password	“”	External Redis password

Example external Redis configuration:

global:
  redis:
    enabled: false
    external:
      host: "redis.example.com"
      port: 6379
      password: "RedisStrongPassword"

---

🚀 Verify Deployment

Check Pod status:

kubectl get pods -n csghub

Check service endpoints:

kubectl get svc -n csghub

---

🔄 Upgrade and Uninstall

Upgrade

helm upgrade csgship csghub/csgship -n csghub -f custom-values.yaml

Uninstall

helm uninstall csgship -n csghub

---

🧭 Common Issues

Issue	Cause	Solution
Cannot connect to main service	Incorrect externalUrl configuration	Check domain and protocol (HTTPS required)
Startup failure	Database or cache misconfiguration	Verify PostgreSQL / Redis host and password
Image pull failure	Private registry authentication issue	Configure image.pullSecrets

---

📘 Production Recommendations

1. Use external PostgreSQL and Redis to reduce local state dependency.
2. Enable TLS / HTTPS access to enhance communication security.
3. Set appropriate resources.requests and limits to prevent node resource contention.