CSGShip

1. Overview

CSGShip is the Intelligent Coding Assistant backend service of the CSGHub platform. It provides core capabilities for CodeSouler (IDE plugin), including intelligent code completion, semantic search, conversational programming, AI code generation, and knowledge retrieval.

Deployed as a standalone service, CSGShip supports independent scaling of compute nodes and horizontal scaling of multiple instances. It is designed to work seamlessly with the main service (CSGHub Server).

2. Environment Requirements

Resource Item	Minimum Configuration	Recommended Configuration
CPU / Memory	4C / 8 GB	8C / 16 GB
Disk Space	10 GB	50 GB+
Architecture	AMD64 / ARM64	Multi-arch support

Software Dependencies

Component	Version Requirement	Description
Kubernetes	1.28+	Cluster environment
Helm	3.12+	Chart management tool
PostgreSQL / Redis	Optional (External)	External managed resources are supported

3. Installation

3.1 Add Helm Repository

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

3.2 Create Namespace (Optional)

kubectl create namespace csghub

3.3 Install CSGShip

Obtain the following information from your CSGHub main service:

domain: Provide a second-level domain. For example, if you provide example.com, the services will be exposed at csgship.example.com and csgship-api.example.com.

externalUrl: Run the following to find the CSGHub URL:

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

hubAPIToken:

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

NATS Credentials:

# Get NATS Username and Password
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

Note: Currently only service names are supported for host (same-cluster deployment).

Execution Command:

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>"

Domestic deployment (use a domestic image registry to accelerate image pulling):

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>" \
  --set global.image.registry="registry.opencsg.com" \
  --set global.imageRegistry="registry.opencsg.com/opencsghq"

3.4 Access Paths

Service URL	Description
http://csgship.example.com	CSGShip Frontend (requires `--set web.oauth`)
http://csgship-api.example.com	CSGShip API Endpoint

4. Configuration Parameters

4.1 Global Configuration

Parameter	Default	Description
`global.gateway.external.domain`	`csghub.example.com`	Primary access domain
`global.gateway.tls.enabled`	`false`	Enable HTTPS / TLS
`global.persistence.size`	`10Gi`	Default PV size
`global.postgresql.enabled`	`true`	Use built-in PostgreSQL
`global.redis.enabled`	`true`	Use built-in Redis
`global.chartContext.isBuiltIn`	`false`	Whether deployed as a sub-module of the main Chart

4.2 Service Configuration

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

4.3 OAuth Configuration

CSGShip supports GitLab OAuth. Set these in your values.yaml:

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

4.4 Storage Configuration

4.4.1 PostgreSQL

Parameter	Default	Description
`global.postgresql.enabled`	`true`	Use built-in PostgreSQL
`global.postgresql.external.host`	none	External PostgreSQL host
`global.postgresql.external.port`	`5432`	External PostgreSQL port
`global.postgresql.external.user`	`csghub`	Username
`global.postgresql.external.password`	`""`	Password
`global.postgresql.external.sslmode`	`disable`	SSL mode
`global.postgresql.existingSecret`	`""`	Reference an existing Secret for the PostgreSQL connection (see note below); only honored when `enabled=false`

💡 For production, use an external managed database:

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

💡 You can also reference an existing Secret via existingSecret to supply the external connection (no need to put credentials in values.yaml). The Secret must be created in the release namespace beforehand. Supported keys (base64-encoded):

POSTGRES_HOST (required) — PostgreSQL host

POSTGRES_PORT — PostgreSQL port (default 5432)

POSTGRES_USER — Username

POSTGRES_PASSWORD — Password

POSTGRES_SSLMODE — SSL mode (disable / require / verify-full, etc.)

Example:
global:
  postgresql:
    enabled: false
    existingSecret: "my-pg-secret"

4.4.2 Redis

Parameter	Default	Description
`global.redis.enabled`	`true`	Use built-in Redis
`global.redis.external.host`	none	External Redis host
`global.redis.external.port`	`6379`	External Redis port
`global.redis.external.password`	`""`	External Redis password
`global.redis.existingSecret`	`""`	Reference an existing Secret for the Redis connection (see note below); only honored when `enabled=false`

💡 You can also reference an existing Secret via existingSecret to supply the external connection (no need to put credentials in values.yaml). The Secret must be created in the release namespace beforehand. Supported keys (base64-encoded):

REDIS_HOST (required) — Redis host

REDIS_PORT — Redis port (default 6379)

REDIS_PASSWORD — Password

REDIS_USER — Username

REDIS_DATABASE — Database index

Example:
global:
  redis:
    enabled: false
    existingSecret: "my-redis-secret"

For external Redis:

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

5. Verification

# Check Pod status
kubectl get pods -n csghub

# Check Service addresses
kubectl get svc -n csghub

6. Upgrade & Uninstallation

6.1 Upgrade

helm upgrade 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>"

6.2 Uninstallation

helm uninstall csgship -n csghub

7. Troubleshooting

Cannot connect to main service: Check if externalUrl protocol (HTTP vs HTTPS) matches the actual CSGHub deployment.
Startup failure: Check logs for PostgreSQL or Redis connection errors.
Image pull failure: Ensure image.pullSecrets are configured if using a private registry.

8. Production Recommendations

External DB/Cache: Use managed PostgreSQL and Redis for better state management.
Enable TLS: Always use HTTPS for production communication.
Resource Limits: Set explicit resources.requests and limits to prevent resource contention.

1. Overview​

2. Environment Requirements​

Software Dependencies​

3. Installation​

3.1 Add Helm Repository​

3.2 Create Namespace (Optional)​

3.3 Install CSGShip​

3.4 Access Paths​

4. Configuration Parameters​

4.1 Global Configuration​

4.2 Service Configuration​

4.3 OAuth Configuration​

4.4 Storage Configuration​

4.4.1 PostgreSQL​

4.4.2 Redis​

5. Verification​

6. Upgrade & Uninstallation​

6.1 Upgrade​

6.2 Uninstallation​

7. Troubleshooting​

8. Production Recommendations​