Skip to main content

Docker Compose

Advantages​

  • Simplified Management: All service dependencies are uniformly orchestrated through Docker Compose

  • Quick Deployment: Start the complete CSGHub service stack with one click

  • Flexible Expansion: Support horizontal expansion of service instances, adjust resource configuration and service scale on demand

  • Production Ready: Meet the application deployment requirements of small and medium-sized enterprises

**Tip: ** It is recommended to use Docker Compose for installation.

Applicable Scenarios​

  • Quickly build a CSGHub demonstration environment
  • Quickly verify CSGHub functions
  • Development and test environment deployment
  • Small and medium-scale production environment deployment

Functional Description​

Two startup modes are provided according to the configuration complexity:

  • Basic Function: All functions except model evaluation, reasoning, fine-tuning, application space, and MCP (the above functions rely on Kubernetes clusters).

  • Complete Function: Contains all ce/ee functions.

    If using complete function, you should configure docker-compose.yml to enable runner and mapping volume for .kube/config. Attention: Please ensure API Server Address in.kube/config can be accessed in container.

Note: When accessing using an IP address, MCP functionality will be limited (this functionality requires domain name support).

System Requirements​

Hardware Requirements​

Resource TypeMinimum ConfigurationRecommended ConfigurationMore
CPU/Memory4 cores 8GB8 cores 16GB
Processor ArchitectureAMD64/ARM64Supports x86 and ARM architectures

Software Requirements​

ComponentsVersion RequirementsVerification CommandsOther Dependencies
Docker Engine≥ 20.10.0docker --version
Docker Compose≥ 2.0.0docker compose version
Kubernetes1.28+ (optional)kubectl version1. Nvidia GPU support requires pre-installation of Nvidia Device Plugin
3. support Dynamic Volume Provisioning

Note: Enabling full functionality requires Kubernetes, otherwise model evaluation, reasoning, fine-tuning, MCP, application space and other functions will not be available.

Installation and Deployment​

Note: By default, csghub.external_url uses port 80 (the default port number :80 can be ignored). If you change the external mapping port of ports 80, make sure to use the same port number in external_url.

Installation and Configuration Instructions​

Container Description​

For user-friendliness, we've merged the original Docker Compose multi-container services into a single container. While this merge is a single container, it still supports multi-host deployment. Each service can be split into its own independent container, providing greater flexibility and easier configuration.

Version Notes​

  • CE Community Free Edition

  • EE Enterprise Edition (Recommended)

    • Includes all features of the Community Edition
    • Enterprise Edition Features - Requires a license to be imported
    • Starship Coding Assistant - Disabled by default

  • Initialization Parameter Description

    Due to the large number of parameters in csghub, only a portion of the configurable parameters are shown in the installation example. For more parameters, see csghub.yaml.sample.

    All configurable parameters in docker-compose.yaml are defined in YAML format via the CSGHUB_OMNIBUS_CONFIG variable, which takes precedence. If the service is already started, there are two ways to adjust these parameters:

    • Redefine CSGHUB_OMNIBUS_CONFIG and restart the container.
    • Enter the container and modify the /etc/csghub/csghub.yaml file. Modified parameters already defined in CSGHUB_OMNIBUS_CONFIG will not take effect.

    Basic Parameter Description:

    • csghub

      • external_url

        Defines the URL for accessing the CSGHub sample, using <scheme>://<domain>:[port]. If <scheme> is http, [port] defaults to 80; if <scheme> is https, [port] defaults to 443. [port] should match the port number reserved for external use in ports. For details, see [Modify Port Number Mapping](#Modify Port Number Mapping).

    • runner

      • enable

        Defaults to false. Upon startup, this service will scan the .kube/config-* files mapped via volumes. If the scanned files are empty, it may fail to run properly. Therefore, this service is disabled by default, but it is essential for running features such as inference and fine-tuning. Please ensure that the Kubernetes cluster is ready before enabling this service.

      • deploy

        • auto_configure

          Defaults to true. This parameter initializes CSGHub's dependencies, such as Argo Workflow, LWS, and KnativeServing, when connecting to a Kubernetes cluster. By default, no configuration is required.

        • knative.services

          • type

            You must define the type of the KnativeServing service to be exposed. This parameter is only valid during the first initialization; once KnativeServing is initialized, it becomes invalid.

          • domain

            Defines the internal domain name used by KnativeServing, primarily for internal access within CSGHub.

          • host

            Defines the external access address assigned to the KnativeServing kourier service.

          • port

            Defines the external access port assigned to the KnativeServing kourier service.

          For more information, see Installing KnativeServing.

      Note: If the service is enabled but the Kubernetes cluster is not ready, the server master service will fail to initialize computing resource data, preventing the master service from becoming ready.

    • About the dataflow container

      This container is the backend service for data processing in the enterprise version. Because some features are still being optimized and the container is relatively complex, it is currently deployed separately. You can connect to Dataflow by adding this container and defining server.dataflow.address. The default database used by Dataflow is the built-in database in the CSGHub container.

Default installation​

  • docker-compose.yml

    services:
      csghub:
        image: opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/omnibus-csghub:v1.10.0-${EDITION:-ee}
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            csghub:
              external_url: "http://csghub.example.com" # Access the CSGHub instance domain name. It is recommended to configure it using the domain name.
            runner:														          # Only for Complete Function Install, else you can remove this entry
              enable: true										          # Whether to enable the Runner service. If disabled, only basic functions can be used.
              deploy:
                knative:
                  services:
                    - type: "NodePort"        # If your Kubernetes cluster supports LoadBalancer, you can use LoadBalancer
                      domain: "app.internal"	# Customize Knative Serving internal domain name
                      host: "192.168.18.10"   # Expose the EXTERNAL-IP of the kourier service
                      port: 30123							# Custom port number, type=LoadBalancer, please specify 
        ports:
          - '80:80'					# Nginx
          - '2222:2222'     # Git Over SSH
          - '5000:5000'     # Container Registry
          - '8000:8000'     # Casdoor
          - '9000:9000'     # Minio
          - '9001:9001'     # Minio Admin UI
        volumes:
          - ./csghub/etc:/etc/csghub
          - ./csghub/logs:/var/log/csghub
          - ./csghub/data:/var/opt/csghub
          - ./csghub/.kube:/etc/csghub/.kube
        restart: always
        shm_size: '256m'

  • Start Service

    docker compose up -d && docker compose ps

  • Stop Service

    docker compose down

Enable Dataflow​

services:
  csghub:
      ......
      CSGHUB_OMNIBUS_CONFIG: |
        ......
        server:
          dataflow:
            address: "http://dataflow:8000"  # Dataflow Address
        ......

  dataflow:     # Dataflow is a CSGHub dataset processing module that can be enabled on demand.
    image: opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/dataflow:latest
    environment:
      CSGHUB_ENDPOINT: "http://csghub.example.com"
      DATABASE_HOSTNAME: "csghub"
      DATABASE_PORT: "5432"
      DATABASE_USERNAME: "dataflow"
      DATABASE_PASSWORD: "8f444970fcde559c"
      DATABASE_DB: "dataflow"
      DATA_DIR: "/data"
      MAX_WORKERS: 50
      RAY_ADDRESS: "auto"
      RAY_ENABLE: false
      RAY_LOG_DIR: "/var/log/dataflow"
      API_SERVER: "0.0.0.0"
      API_PORT: 8000
      AZURE_OPENAI_ENDPOINT: "$AZURE_OPENAI_ENDPOINT"
      AZURE_OPENAI_API_KEY: "$AZURE_OPENAI_ENDPOINT"
      OPENAI_API_VERSION: "$OPENAI_API_VERSION"
      AZURE_MODEL: "$AZURE_MODEL"
      ENABLE_OPENTELEMETRY: false
    volumes:
      - ./csghub/data/dataflow:/data
      - ./csghub/logs/dataflow:/var/log/dataflow
    restart: always

Enable Starship​

services:
  csghub:
    ......
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        ......
        starship:
          enable: true			# Enable Starship Coding Assistant
    ports:
      ......
      - '8001:8001'     # Starship Portal
      - '8002:8002'     # Starship-API Admin Console
      ......

Install Edition EE​

  • Start Service

    EDITION=ce docker compose up -d && docker compose ps

    Other features are the same as the EE version.

Instance Access​

  1. Instance URL

    See csghub.external_url in docker-compose.yml.

  2. Log in to the csghub container

    docker compose ps && docker exec -it <container> bash

  3. View the default administrator account password

    cat /etc/csghub/init_root_password

Configuration instructions (from high to low)​

  1. Environment variable configuration

    • CSGHUB_OMNIBUS_CONFIG

      Function: Inject dynamic configuration parameters when starting Docker Compose Features: It has the highest priority and will overwrite the same parameters of other configuration sources Usage scenario: Suitable for parameter injection during temporary adjustment or containerized deployment

  2. Main configuration file

    • /etc/csghub/csghub.yaml

      Content: Complete parameter set, supports all configurable items Suggestion: Only modify key parameters as needed, unconfigured items automatically inherit default values Permissions: It is recommended to retain the system default permissions (usually requires root permissions to modify)

  3. Default configuration baseline

    • /opt/csghub/etc/csghub/default.yaml

      Function: Provides baseline default values for all parameters Features:

      • Lowest priority, only effective when other configurations are undefined
      • Direct modification is not recommended (may be overwritten during upgrade)
      • Can be used as a configuration template reference

For more references to csghub.yaml.sample.

Service Management​

  • csghub-ctl
CommandDescription
--helpView help
reconfigureRefresh all service configuration files and restart services as needed
startStart service
restartRestart service
stopStop service
reloadReload service
tailTrack service log
statusView service status
  • csghub-psql: Quick access csghub_server database

FAQ​

About .kube/config​

.kube/config file is an important configuration file for accessing Kubernetes clusters. CSGHub will rely on this file when running.

About external services​

By default, the following components will be automatically configured through runner.deploy.autoConfigure=true. This configuration depends on the runner.deploy.knative.services[] parameter passed in when starting the service. If there are some reasons why the automatic configuration cannot be completed, you can try to manually install and configure it in the following ways:

Modify port number mapping​

Currently, the following port numbers are exposed:

  • '80:80' # Nginx

  • '2222:2222' # Git Over SSH

  • '5000:5000' # Container Registry

  • '8000:8000' # Casdoor

  • '8001:8001' # Starship Portal

  • '8002:8002' # Starship-API Admin Console

  • '9000:9000' # Minio

  • '9001:9001' # Minio Admin UI

  • Modify Nginx port

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            csghub:
              external_url: "http://csghub.example.com:8080" 
        ports:
          - '8080:80'   # Only Update Exposed Port
       ......

  • Modify Git over SSH port

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            gitlab_shell:
              ssh_port: 22222
        ports:
          - '22222:22222'   # Update Both Ports
       ......

  • Modify Container Registry port

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            csghub:
              external_url: "http://csghub.example.com:8080" 
            runner:
              registry:
                prefix: "csghub.example.com:5001/csghub/"
        ports:
          - '5001:5000'   # Only Update Exposed Port
       ......

  • Modify Casdoor port

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: |
            casdoor:
              listen: "127.0.0.1:8005"
        ports:
          - '8005:8005'   # Update Both Ports
       ......

  • Modify Starship port

    services:
    ......
        environment:
          CSGHUB_OMNIBUS_CONFIG: | 
            starship:
              listen: 
                frontend: "127.0.0.1:8006"
                api: "127.0.0.1:8007"
        ports:
          - '8006:8006'   # Update Both Ports
          - '8007:8007'   # Update Both Ports
       ......

  • Modify Minio port

    services:
    ......
        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'   # Only Update Exposed Port
          - '9006:9001'   # Only Update Exposed Port
       ......

Login failed: Unknown login error, please contact the administrator​

The most common causes of this issue are the following:

  1. The hostname field was added to the docker-compose.yml file as the access domain name.

    services:
      csghub:
        image: opencsghq/omnibus-csghub:v1.10.0-ce
        hostname: "xxx" # Remove this parameter, or ensure it is inconsistent with the domain name defined in `external_url`.

  2. The host's hosts domain name resolves to 127.0.0.1.

    Please ensure that the domain name defined in external_url resolves to an address other than 127.0.0.1 or localhost.

Feedback​

If you encounter any problems during use, you can submit feedback through the following methods: