Deployment Guide

💡 Important Note:

The Docker Compose deployment method does not include dataflow and runner services; these need to be integrated with the corresponding services in Kubernetes.

📘 Overview

CSGHUB provides a one-click Docker deployment method that uses Docker Compose to quickly start the complete service stack.

This deployment option is suitable for:

Quick feature evaluation or demo environments
Development and testing environments
Small-scale production environments (recommend quick install)

💡 Recommendation: For production-grade setups, use the Helm Chart deployment method.

⚙️ Advantages

Simplified Management – Use Docker Compose to orchestrate all service dependencies
Quick Deployment – Start a complete CSGHub service stack with one command
Flexible Scaling – Supports horizontal scaling and multi-node deployment
Production Ready – Suitable for small to medium enterprise workloads

🧩 Deployment Modes

CSGHUB Docker deployment supports two operational modes:

Mode	Feature Scope	Dependencies
Basic Mode	Includes all features except model evaluation, inference, fine-tuning, AppSpace, and MCP	No Kubernetes required
Full Mode	Includes all CE/EE features	Requires Kubernetes cluster connection

⚠️ Note: When accessing via IP address, MCP functionality is limited. It is recommended to use a domain name for full functionality.

🧮 System Requirements

Hardware Requirements

Resource Type	Minimum	Recommended
CPU / Memory	4 cores / 8GB	8 cores / 16GB
Architecture	-	AMD64 / ARM64

Software Requirements

Component	Version	Verification Command
Docker Engine	≥ 20.10	docker --version
Docker Compose	≥ 2.0	docker compose version
Kubernetes (optional)	≥ 1.28	kubectl version

🧠 Note: Full features (inference, fine-tuning, MCP, AppSpace, etc.) require access to a Kubernetes cluster.

🏗️ Installation & Configuration

🔹 Container Architecture

This version uses a unified single-container architecture:

All core components are packaged within one container image, while still allowing modular deployments for flexibility.

🔹 Edition Types

CE (Community Edition) – Free and open source
EE (Enterprise Edition) – Includes all CE features plus enterprise extensions (requires a license)

🔹 Configuration Sources & Priority

CSGHUB configuration parameters can be defined through multiple sources:

Priority	Source	Description
🥇 1	Environment variable `CSGHUB_OMNIBUS_CONFIG`	Usage: Injects dynamic configuration during Docker startup. Priority: Highest — overrides all other sources. Use case: Ideal for containerized or temporary parameter injection.
🥈 2	`/etc/csghub/csghub.yaml`	Content: Full configuration set. Recommendation: Modify only key parameters; unspecified items inherit defaults. Permission: Typically requires root privileges.

🧩 Default Naming Rules

Databases, object stores, and volumes follow the format: csghub-<service>

🧱 Default Installation Example

⚠️ Note: The Runner service has been decoupled from the main CSGHub container. It is now deployed as an independent agent within the Kubernetes cluster. Please remove any legacy Runner configuration.

services:
  csghub:
    image: opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/omnibus-csghub:latest
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        csghub:
          external_url: "http://csghub.example.com"
    ports:
      - '80:80'
      - '2222:2222'
      - '8000:8000'
      - '9000:9000'
    volumes:
      - ./csghub/etc:/etc/csghub
      - ./csghub/logs:/var/log/csghub
      - ./csghub/data:/var/opt/csghub
      - ./csghub/.kube:/etc/csghub/.kube
    restart: always

For more options, please refer to: csghub.yaml.sample.
The tag latest defaults to the latest release version of ee.
See more tags.

🚀 Start and Verify

# Start services
docker compose up -d && docker compose ps

# Check services
docker exec -it <container> csghub-ctl status

⚠️ Troubleshooting Tips:

If the service is not accessible after startup, check the following:

Ensure the external_url port matches the Docker mapping (e.g., if using port 8080, set 8080:80).

Avoid using IP addresses like localhost, 127.0.0.1, or internal ranges (172.17.x.x / 172.21.x.x).

It takes a few minutes for the container to become ready after it starts.

🌐 Accessing the Instance

URL: external_url

Login Credentials:

docker exec -it <container> cat /etc/csghub/init_root_password

🔧 Enabling CSGShip

To enable CSGShip, append the following to your configuration:

services:
  csghub:
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        starship:
          enable: true
    ports:
      - '8001:8001'
      - '8002:8002'

🔧 Configuring Dataflow

The Dataflow service handles dataset processing and labeling.

Due to its complexity, it is deployed separately.

You can link it by defining server.dataflow.address.

Deployment options:

🔧 Configuring Runner

Since Runner tightly integrates with Kubernetes, it is only available via Helm Chart.

Runner Chart

🌍 Using External Resources (Recommended for Production)

environment:
  CSGHUB_OMNIBUS_CONFIG: |
    global:
      postgresql:
        enabled: false

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

      minio:
        enabled: false
        external:
          endpoint: "https://s3.amazonaws.com"
          accessKey: "AKIAxxxx"
          secretKey: "xxxx"
          region: "us-east-1"

📦 Service Management Commands

csghub-ctl

NAME:
   csghub-ctl - A command-line tool to manage csghub services, with self-compiled and inheriting all other commands

USAGE:
   csghub-ctl [global options] command [command options]

VERSION:
   x.x.x

COMMANDS:
   reconfigure  Reconfigure all services based on the configuration file
   praefect     Commands for managing praefect service
   consul       Commands for managing consul service
   psql         Commands for managing postgresql service
   patroni      Commands for managing patroni service
   mc           Commands for managing minio service
   kyml         Checking if Kubernetes YAML resources exists.
   creds        Commands for fetch credentials.
   tail         Tail services logs
   start        Start service
   stop         Stop service
   restart      Restart service
   status       Show status of service
   enable       Enable a service
   disable      Disable a service
   help, h      Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help
   --version, -v  print the version

reconfigure

If you modify the configuration in the container using the configuration file /etc/csghub/csghub.yaml, you can use this command to refresh the configuration of all services. The corresponding service will automatically restart after the configuration change.
praefect

Inherits all subcommands of GitLab Gitaly Praefect, used to operate the Praefect Gitaly cluster.
consul

Inherits all subcommands of HashiCorp Consul, used to operate the Consul cluster.
psql

Inherits all group commands of PostgreSQL PSQL, used to operate the PostgreSQL database.
patroni

Inherits the Patroni Patroni-CTL command, used to operate the PostgreSQL Patroni cluster.
mc

Inherits the HashiCorp Minio mc command, used to operate Minio.
kyml

Used to validate Kubernetes YAML resource manifests, including operations such as creation, update, and rebuild.
creds

Used to retrieve credentials for commonly used service components.
tail

View logs for a specific service or all services in real time.
status

View the status of a specific service or all services.
start/stop/restart/enable/disable

(Omitted)

csghub-psql

This command allows you to quickly log in to the database.

🧭 Troubleshooting

Ensure hostname in docker-compose.yml is not the same as the external_url domain.
Verify that the host machine’s /etc/hosts file resolves to a non-127.0.0.1 IP address.

❓ Changing Port Mappings

The following ports are exposed by default:

Service	Default Port	Description
Nginx	80	Main web entry point
Git SSH	2222	Git repository access
Casdoor	8000	Authentication service
CSGShip	8001	CSGShip frontend
CSGShip-API	8002	CSGShip API backend
MinIO	9000	Object storage endpoints

Examples:

Nginx Port

csghub:
  environment:
    CSGHUB_OMNIBUS_CONFIG: |
      csghub:
        external_url: "http://csghub.example.com:8080"
  ports:
    - '8080:80'

Git SSH Port

csghub:
  environment:
    CSGHUB_OMNIBUS_CONFIG: |
      gitlab_shell:
        ssh_port: 22222
  ports:
    - '22222:22222'

Casdoor Port

csghub:
  environment:
    CSGHUB_OMNIBUS_CONFIG: |
      casdoor:
        listen: "127.0.0.1:8005"
  ports:
    - '8005:8005'

CSGShip Port

csghub:
  environment:
    CSGHUB_OMNIBUS_CONFIG: |
      csgship:
        listen:
          frontend: "127.0.0.1:8006"
          api: "127.0.0.1:8007"
  ports:
    - '8006:8006'
    - '8007:8007'

MinIO Port

csghub:
  environment:
    CSGHUB_OMNIBUS_CONFIG: |
      csghub:
        external_url: "http://csghub.example.com:8080"
      server:
        s3:
          endpoint: "csghub.example.com:9005"
          internal_endpoint: "127.0.0.1:9000"
      portal:
        s3:
          endpoint: "csghub.example.com:9005"
      registry:
        storage:
          s3:
            regionendpoint: "http://csghub.example.com:9005"
  ports:
    - '9005:9000'
    - '9006:9001'

📘 Overview​

⚙️ Advantages​

🧩 Deployment Modes​

🧮 System Requirements​

Hardware Requirements​

Software Requirements​

🏗️ Installation & Configuration​

🔹 Container Architecture​

🔹 Edition Types​

🔹 Configuration Sources & Priority​

🧩 Default Naming Rules​

🧱 Default Installation Example​

🚀 Start and Verify​

🌐 Accessing the Instance​

🔧 Enabling CSGShip​

🔧 Configuring Dataflow​

🔧 Configuring Runner​

🌍 Using External Resources (Recommended for Production)​

📦 Service Management Commands​

🧭 Troubleshooting​

❓ Login Failure (Invalid Location or Redirect)​

❓ Changing Port Mappings​

Nginx Port​

Git SSH Port​

Casdoor Port​

CSGShip Port​

MinIO Port​