Troubleshooting

1. Unable to access CSGHub via external_url after container startup

If you cannot access the service, please check the following:

Check Service Readiness

Run the following command to verify that all internal components are running:

docker exec -it csghub-omnibus csghub-ctl status

Port Mapping Configuration

Under normal circumstances, the external mapping port for port 80 should match the port used in the external_url.

Example 1 (Standard HTTP):

......
    # Use block scalar style for better readability of complex configs
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        csghub:
          external_url: "http://csghub.example.com"
    
    # Ports mapping for accessing
    ports:
      - '80:80'

Example 2 (Custom Port):

    # Use block scalar style for better readability of complex configs
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        csghub:
          external_url: "http://csghub.example.com:8080"
    
    # Ports mapping for accessing
    ports:
      - '8080:80'

Network Conflicts & Hostname

• The address resolved by external_url must not conflict with the Docker container network (avoid using localhost, 127.0.0.1, or subnets like 172.17.0.0/8, 172.21.0.0/8).
• Do not specify a hostname parameter in docker-compose.yaml that is identical to the domain used in external_url.

2. Container fails to start due to configuration rendering error

This issue is usually caused by formatting errors in the environment.CSGHUB_OMNIBUS_CONFIG variable.

• This variable must contain valid YAML syntax.
• Indentation must strictly follow YAML standards.
• CRITICAL: Do not use Tabs for indentation; use spaces only.

3. Modifying Port Mappings

The following table lists the default ports exposed by the service:

Service	Default Port	Purpose
Nginx	80	Main access entry point
Git SSH	2222	Code repository access
Casdoor	8000	Authentication center
CSGShip	8001	CSGShip frontend access
CSGShip-API	8002	CSGShip API access
MinIO	9000	Object storage service

3.1 Modify Nginx Port

services:
......
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        csghub:
          external_url: "http://csghub.example.com:8080" 
    ports:
      - '8080:80'   # Modify external port only
   ......

3.2 Modify Git Over SSH Port

services:
......
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        gitlab_shell:
          ssh_port: 22222
    ports:
      - '22222:22222'   # Modify both internal and external ports
   ......   

3.3 Modify Casdoor Port

services:
......
    environment:
      CSGHUB_OMNIBUS_CONFIG: |
        casdoor:
          listen: "127.0.0.1:8005"
    ports:
      - '8005:8005'   # Modify both internal and external ports
   ......     

3.4 Modify CSGShip Port

services:
  ......
    environment:
      CSGHUB_OMNIBUS_CONFIG: | 
        csgship:
          listen: 
            frontend: "127.0.0.1:8006"
            api: "127.0.0.1:8007"
    ports:
      - '8006:8006'     # Frontend
      - '8007:8007'     # API
    ......

3.5 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'     # API External Port
      - '9006:9001'     # Console External Port
......

4. Feedback

For any other issues not covered here, please submit a feedback report via our official issue tracker.