Skip to main content

Configuration Specifications

Note: All configuration modifications should be made via environment variables or the default configuration file. Otherwise, reconfiguring the service may overwrite other parameters.

1. Configuration Overview​

When starting via Docker, there are two ways to pass configurations:

  1. Via Variable: CSGHUB_OMNIBUS_CONFIG
  2. Via Config File: /etc/csghub/csghub.yaml

The priority is ranked from highest to lowest respectively, and both follow the same configuration format.

2. Environment Variables​

The CSGHUB_OMNIBUS_CONFIG environment variable is primarily used for convenient configuration injection when starting with Docker Compose.

3. Configuration File​

The /etc/csghub/csghub.yaml file is the default persistent parameter file.

  • Most parameters in the file are commented out by default; the commented values represent the default settings.
  • The file must strictly follow YAML format, otherwise, it will cause service configuration errors.

4. Common Parameters​

4.1 CSGHub Core​

  • external_url
    • Default: http://csghub.example.com
    • Description: Defines the URL to access the CSGHub instance. It is strongly recommended to use a domain name. While IP addresses can be configured, they may cause certain features to become unavailable.

4.2 Nginx​

  • ssl_certificate / ssl_certificate_key
    • Default: Not configured.
    • Description: Domain certificates required to enable TLS (HTTPS) access.
  • rate_limit
    • Default: Not configured.
    • Description: Sets the rate limit for incoming requests.

4.3 External Service Integration​

By default, CSGHub uses built-in services. Configuring these parameters connects to external instances:

  • postgresql
    • Description: Once configured, CSGHub uses the external database. Note that this does not automatically disable the built-in DB; you must explicitly disable it via postgresql: { enable: false }.
    • Note: Multiple services (Portal, Casdoor, Temporal, etc.) depend on this database.
  • redis
    • Description: Behavior is identical to PostgreSQL. Connects to external Redis.
  • s3
    • Description: Behavior is identical to PostgreSQL. Used to connect to external S3-compatible object storage instead of the built-in Minio.
  • gitaly
    • Description: Used for external Gitaly cluster integration. Please consult our engineers for specific deployment methods.

4.4 Functional Components​

  • dataflow
    • Default: Disabled.
    • Description: Connects to the Dataflow service deployed via the Dataflow Chart. Refer to [#dataflow-configuration] for more details.
  • notifier.smtp
    • Default: Not configured.
    • Description: Enables email notification services.

4.5 Storage and Ports​

  • gitaly.storage
    • Default: /var/opt/csghub/gitaly/repositories
    • Description: Specifies the data directory for the Git storage service. If modified on an existing installation, data must be migrated manually.
  • gitlab_shell.ssh_port
    • Default: 2222
    • Description: Specifies the service port for pulling code via Git SSH.
  • minio.auth
    • Default: Auto-generated.
    • Description: Specifies the default administrator credentials.
  • postgresql.data_dir
    • Default: /var/opt/csghub/postgresql/data
    • Description: Specifies the default directory for database data files.

4.6 Other Runtime Parameters​

Some parameters are automatically calculated based on the hardware environment, while others remain configurable:

  • max_connections
  • shared_buffers
  • checkpoint_timeout
  • ... (and more)

5. More References​

For a complete list of parameters, please check the sample file: