Helix TeamHub Configuration
The /var/opt/hth/shared/hth.json
configuration file and some of the flags it provides should be familiar by now. This is where Helix TeamHub configuration settings are kept, including settings manipulated through Helix TeamHub Admin UI from the Helix TeamHub Bootstrap phase. This configuration file is also part of Helix TeamHub Backups, if enabled.
Every time Helix TeamHub is reconfigured, the configuration file is read and the configuration is applied to all of Helix TeamHub services. Some of the configuration flags dictate what mode of deployment Helix TeamHub is running, where others simply override default Helix TeamHub settings.
Format
The configuration file is formatted as JSON. It is important to keep the correct format of the file, otherwise the Helix TeamHub reconfiguration will not work. JSONLint is a trusted open-source JSON linter option to help verify the syntax of the JSON contents.
Remember that duplicate keys override the previously defined keys.
To see the current configuration applied to the server, run the following command:
sudo hth-ctl show-config
Overriding Defaults
Helix TeamHub comes with many sensible defaults for both service and application behavior. If the default configuration needs to be adjusted, use the dictionary provided below as a reference.
Each configuration flag has a section, for example app
, nginx
, etc. These sections separate settings into logical categories. To use the dictionary, simply merge the section to the existing Helix TeamHub configuration file at /var/opt/hth/shared/hth.json
with a required key and value.
Whenever changing any of the configurations, pay attention to the type of the key and where available refer to the linked documentation. Also, remember that configuration is not applied until the sudo hth-ctl reconfigure
command has been run.
Section: apache
This section groups Helix TeamHub Apache-related settings.
Key | Type | Default | Description |
---|---|---|---|
timeout
|
Integer | 120
|
Defines the length of time Apache httpd will wait for I/O |
Section: app
This section groups instance and general application related settings.
Key | Type | Default | Description |
---|---|---|---|
backups_email
|
String | email |
Allows overriding receiver of backup related emails. |
default_company
|
String | Default company short name to use with login | |
email
|
String | support@FQDN
|
Email of the sender of all outgoing emails and links to Support team |
hostname
|
String | FQDN
|
Helix TeamHub application hostname |
http_proxy
|
String | Defines HTTP proxy to use with external services like hooks. Provide absolute url including possible credentials: http://user:password@proxy.com:8008 . |
|
is_cluster
|
Boolean | false
|
Defines whether Helix TeamHub runs in Cluster or HA mode |
is_ssl
|
Boolean | false
|
Defines whether Helix TeamHub enforces SSL |
notifications_email
|
String | email |
Allows overriding sender of notification related emails. |
registrations_email
|
String | email |
Allows overriding sender of registration related emails. |
ssh_port
|
Integer | 22 |
Defines SSH port for Git and Mercurial clone urls when the instance is using non-standard SSH port. |
Section: audit
This section groups Helix TeamHub audit logging related settings.
Key | Type | Default | Description |
---|---|---|---|
logrotate_frequency
|
String | daily
|
Frequency of logrotate rotation |
logrotate_rotate
|
Integer | 90
|
Number of logrotate files to keep |
logrotate_size
|
Integer | Size of logrotate rotation. Does not rotate by size by default |
Section: backend
This section groups Helix TeamHub backend (APIs, Helix TeamHub Admin) application-related settings.
Key | Type | Default | Description |
---|---|---|---|
auth_method
|
String | builtin
|
Defines Helix TeamHub Authentication type. Allowed: builtin , ldap , or both |
backup_s3
|
Boolean | false
|
Defines whether asset backups need to be taken offline to Amazon S3. Requires backups section configuration. |
backups
|
Boolean | false
|
Defines whether Helix TeamHub asset backups are enabled |
command_timeout | Integer | 60 | Timeout for command execution, in seconds. |
company_disk_usage_calculator_queue_size | Integer | 1 | Number of workers performing company disk usage calculation jobs. |
db_host
|
String | localhost
|
MongoDB hostname for Cluster or HA setup |
db_password
|
String | MongoDB password | |
db_pool_size
|
Integer | 10
|
MongoDB connection pool size |
db_port
|
Integer | 4002
|
MongoDB port |
db_username
|
String | MongoDB username | |
diff_file_max_bytes
|
Integer | 51200
|
Maximum number of bytes for a file in a diff |
diff_max_bytes
|
Integer | 1024000
|
Maximum number of bytes for a diff output |
diff_max_files
|
Integer | 150
|
Maximum number of files in a diff |
diff_max_lines
|
Integer | 50000
|
Maximum number of lines in a diff |
diff_process_max_bytes
|
Integer | 2048000
|
Maximum number of bytes to process for a diff |
diff_timeout
|
Integer | 5
|
Timeout in seconds for generating a diff |
es_hosts
|
Array | nil
|
Array of Elasticsearch host hashes, with supported keys: host , port , scheme , user , password . |
es_index_prefix
|
String | nil
|
Defines the optional index name prefix for Elasticsearch indices. |
es_number_of_replicas
|
Integer | 1
|
Defines the number of replicas for Elasticsearch indices. |
es_number_of_shards
|
Integer | 5
|
Defines the number of shards to use with Elasticsearch indices. |
es_ssl_verify
|
Boolean | true
|
Defines whether to validate Elasticsearch host certificate. |
events_queue_size | Integer | 2 | Number of workers performing event jobs. |
failed_login_interval
|
Integer | 2
|
Minimum time between failed login attempts |
failed_login_limit
|
Integer | 6
|
Limit of failed login attempts in specified time frame |
failed_login_period
|
Integer | 60
|
Time frame for failed_login_limit |
hooks_queue_size | Integer | 2 | Number of workers performing repository event jobs. |
index_queue_size | 1 | Number of workers performing code search indexing jobs | |
ldap_collaborators_base
|
String | LDAP search base for collaborators | |
ldap_collaborators_enabled
|
Boolean | false
|
LDAP authentication for collaborators |
ldap_collaborators_filter
|
String | LDAP search filter used when finding collaborators | |
ldap_domain_base
|
String | LDAP search base for users | |
ldap_email
|
String | LDAP account email field mapped to Helix TeamHub email | |
ldap_encryption
|
String | plain
|
LDAP encryption. Allowed: plain , start_tls , simple_tls |
ldap_filter
|
String | LDAP search filter used when finding users | |
ldap_first_name
|
String | LDAP account first name field | |
ldap_groups
|
String | LDAP field defining users groups | |
ldap_groups_base
|
String | LDAP groups search base | |
ldap_groups_from_user
|
Boolean | false
|
LDAP users contain group information |
ldap_host
|
String | LDAP hostname | |
ldap_interface_max_connections | Integer | 10000 | Maximum connections for a child process until it is replaced with a new fork in the LDAP interface |
ldap_interface_max_idle | Integer | 10 | Maximum idle time, in seconds, for a child process after stopping serving requests until it is replaced with a new fork in the LDAP interface |
ldap_interface_max_servers | Integer | 32 | Maximum number of forked child processes in the LDAP interface |
ldap_interface_min_servers | Integer | 4 | Minimum number of forked child processes in the LDAP interface |
ldap_interface_timelimit | Integer | 30 | Maximum server-side time limit, in seconds, for a request in the LDAP interface |
ldap_last_name
|
String | LDAP account last name field | |
ldap_password
|
String | LDAP search password | |
ldap_port
|
String | LDAP port | |
ldap_short_name
|
String | LDAP account ID field mapped to Helix TeamHub login | |
ldap_source
|
String | LDAP sync identifier | |
ldap_ssl_verify | Boolean | false | Defines whether to validate external LDAP host certificate |
ldap_user
|
String | LDAP search username | |
license_expire_notify
|
String | 30,14,7,3
|
Defines the intervals (number of days) before license expiration to notify instance admins through email. |
merge_queue_size | Integer | 2 | Number of workers performing merge jobs. |
merge_timeout | Integer | 120 | Timeout for code review merge in seconds. |
password_expire_count
|
Integer | 0
|
Defines the number of old passwords that cannot be used again. Value of 0 allows reusing old passwords. |
password_expire_days
|
Integer | 0
|
Defines the maximum number of days a password can be used before it expires. Value of 0 means that passwords never expire. |
password_expire_notify
|
Integer | 7
|
Defines the number of days before password expiration to notify accounts. |
password_validation_entropy
|
Integer | -1
|
Defines the desired password entropy level related to possible email , short_name , first_name , last_name field values using Levenshtein algorithm. Value 0 means exact matching (checks if password is the same like a value of one of aforementioned fields). Value greater than 0 defines a threshold of similarity password must fulfill. Value less than 0 turns off this validation (default). |
password_validation_format
|
String | /(?=.*[[:upper:]])(?=.*[[:lower:]])(?=.*[[:digit:]]).*/
|
Defines the password format requirements for account password validation. By default, password validation requires a minimum of one uppercase letter, one lowercase letter, and one digit. To remove the requirement for a specific password validation format, set password_validation_format to |
password_validation_range
|
String | 8..100
|
Defines the minimum and maximum length for account password validation. |
pilsner_timeout | Integer | 55 | Pilsner request timeout in seconds. |
redis_host
|
String | localhost
|
Redis hostname for Cluster or HA setup |
redis_password
|
String | Redis password | |
redis_port
|
Integer | 6379
|
Redis port |
repository_gc_queue_size | Integer | 1 | Number of workers performing garbage collection jobs. |
search_engine
|
String | nil
|
Defines the search engine to use with Code Search. Supported values: nil and elasticsearch . |
Section: backups
This section groups Helix TeamHub Backups related settings.
Key | Type | Default | Description |
---|---|---|---|
keep
|
Integer | 30
|
How many backups to keep before oldest backup gets removed (Archival method only) |
s3_access_key
|
String | Amazon S3 access key for offline backups | |
s3_bucket
|
String | Amazon S3 bucket name for offline backups | |
s3_key_id
|
String | Amazon S3 key ID for offline backups | |
s3_region
|
String | Amazon S3 region for offline backups |
Section: docker_registry
This section groups Helix TeamHubDocker Registry related settings.
Key | Type | Default | Description |
---|---|---|---|
backups | Boolean | false | Whether Docker backups are enabled |
backups_keep
|
Integer | 5
|
How many backups to keep before oldest backup gets removed |
log_level
|
String | warn
|
Log level for Docker service |
storage_driver | String | filesystem | Docker storage driver to use, see Docker Registry |
storage_settings | Object | Docker storage driver options, see Docker Registry storage driver on the Docker website |
Section: gconn
This section groups the Git Connector (Gconn) settings.
Key | Type | Default | Description |
---|---|---|---|
helix_user | string | nil | Helix server user of Git Connector |
host | string | nil | Hostname of the server Git Connector is installed on |
https_enabled | Boolean | false | Defines whether https is enabled or disabled for Git Connector |
https_port | Integer | nil | Https protocol port. |
ssh_enabled | Boolean | false | Defines whether SSH is enabled or disabled for Git Connector |
ssh_port | integer | nil | SSH protocol port |
user | string | nil | OS user of the Git Connector |
Section: helix
This section groups Helix server connection settings.
Key | Type | Default | Description |
---|---|---|---|
charset | string | utf8 | Character set encoding on the Helix server. For example, utf8or none. |
p4port | string | nil | The hostname or IP address and port for the Helix server, in the form of: host:port |
password | string | nil | Password or ticket for the Helix server super user |
sync_interval | string | */5 * * * * | Interval to sync with the Helix server. Set in Cron format, default is every 5 minutes |
user | string | nil | An existing Helix server user with super level privileges. This user must have unlimited ticket timeout |
Section: logging
This section groups Helix TeamHub logging related settings.
Key | Type | Default | Description |
---|---|---|---|
logrotate_frequency
|
String | daily
|
Frequency of logrotate rotation |
logrotate_rotate
|
Integer | 30
|
Number of logrotate files to keep |
logrotate_size
|
Integer | Size of logrotate rotation. Does not rotate by size by default. | |
svlogd_num
|
Integer | 30
|
Number of SV log files to keep |
svlogd_size
|
Integer | 209715200
|
The maximum size when SV rotation should happen (200MB) |
svlogd_timeout
|
Integer | 86400
|
Number of seconds when SV rotation should happen (24 hours) |
Section: mongodb
This section groups Helix TeamHub MongoDB database related settings, which are usually required in Cluster or HA deployment for tools such as Helix TeamHub Backups accessing MongoDB database.
Key | Type | Default | Description |
---|---|---|---|
backup_s3
|
Boolean | false
|
Defines whether MongoDB backups need to be taken offline to Amazon S3. Requires backups section configuration |
backups
|
Boolean | false
|
Defines whether Helix TeamHub MongoDB backups are enabled |
password
|
String | MongoDB password | |
port
|
Integer | 4002
|
MongoDB port |
username
|
String | MongoDB username |
Section: nginx
This section groups Helix TeamHub Nginx related settings.
Key | Type | Default | Description |
---|---|---|---|
cors_allowed_domains | string or an array of strings | "*" | Cross-Origin Resource Sharing (CORS) controls the external domains that can be used with Helix TeamHub.
|
csp_header | string | default-src 'self'; style-src 'self' 'unsafe-inline'; img-src * data: blob: | Content-Security-Policy header. An empty value omits the header. |
enable_sslv3
|
Boolean | false
|
Whether SSLv3 should be enabled, see Poodle vulnerability |
keepalive_timeout
|
Integer | 65
|
Number of seconds for keep-alive connection |
max_body_size
|
String | 4G
|
Max size of client request body |
proxy_read_timeout
|
Integer | 120
|
Number of seconds for reading a response from backend services |
proxy_send_timeout
|
Integer | 120
|
Number of seconds for sending a request to backend services |
server_names
|
String | _
|
Server names Nginx will listen on |
ssl_ciphers
|
String | See default nginx ciphers below [1] | Specifies enabled ciphers in the format understood by the OpenSSL library |
ssl_protocols | String | TLSv1.1 TLSv1.2 TLSv1.3 | SSL protocols to enable. |
worker_connections
|
Integer | 1024
|
Number of Nginx simultaneous worker connections |
worker_processes
|
Integer | 2
|
Number of Nginx worker processes to start |
[1] Default nginx ciphers:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA
Section: opensshp
This section groups OpenSSH related settings.
Key | Type | Default | Description |
---|---|---|---|
enable | Boolean | false | Whether the bundled OpenSSH is used or not, see OpenSSH. |
Section: pilsner
This section groups settings related to Helix authentication.
Key | Type | Default | Description |
---|---|---|---|
helix_groups_exclude_regex |
String |
Names of groups to be excluded from mirroring between Helix server and Helix TeamHub, specified as a comma-delimited list of Ruby regular expressions, for example: ^swarm-group$ The specified groups do not appear in the TeamHub UI. Important
By default, TeamHub ignores all groups starting with HTH- and all legacy Perforce product groups in Helix server, such as Swarm groups. |
|
helix_groups_include_regex |
String |
Names of groups to be included when mirroring between Helix server and Helix TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^swarm-group$ The specified groups appear in the TeamHub UI. |
|
helix_timeout | Integer | 50 | Helix server request timeout in seconds. |
helix_users_exclude_regex |
String |
|
Names of users to be excluded from mirroring between Helix server and Helix TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^(user1|user2)$ The specified users do not appear in the TeamHub UI. |
helix_users_from_groups_exclude_regex |
String |
Names of groups to exclude users from when mirroring between Helix server and Helix TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^perforce-group$ The users from the specified groups do not appear in the TeamHub UI. |
|
helix_users_from_groups_include_regex |
String |
|
Names of groups to include users from when mirroring between Helix server and Helix TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^perforce-group$ The users from the specified groups appear in the TeamHub UI. |
helix_users_include_regex |
String |
Names of users to be included while mirroring between Helix server and Helix TeamHub, specified as a comma delimited list of Ruby regular expressions, for example: ^(user1|user2)$ The specified users appear in the TeamHub UI. |
|
host | string | localhost | Pilsner service hostname. |
port | integer | 9292 | Pilsner service port. |
Section: postfix
This section groups Helix TeamHub local Postfix MTA mailing settings.
Key | Type | Default | Description |
---|---|---|---|
masquerade_domain
|
String | Domain of the email key | Masquerade domain |
message_size_limit
|
Integer | 20000000
|
Max size of the message in bytes |
password
|
String | Password for SASL authentication | |
relay_host
|
String | Relay hostname | |
relay_port
|
Integer | 25 |
Relay port |
sasl_auth_enable
|
Boolean | false
|
Whether SASL authentication is enabled |
tls_auth_enable
|
Boolean | false
|
Whether TLS is used |
tls_ca_crt_bundle
|
String | TLS CA certificates file | |
user_name
|
String | Username for SASL authentication |
Section: puma_pilsner
This section groups Helix TeamHub Puma Pilsner server related settings.
Key | Type | Default | Description |
---|---|---|---|
max_memory
|
Integer | 1000
|
Maximum total memory (MB) for Puma Pilsner when multiple workers are used |
max_threads
|
Integer | 4
|
Maximum size of worker's thread pool |
min_threads
|
Integer | 0
|
Minimum size of worker's thread pool |
worker_processes
|
Integer | 2
|
Number of Puma Pilsner worker processes to start |
Section: redis
This section groups Redis related settings.
Key | Type | Default | Description |
---|---|---|---|
password | string | Redis server password | |
port | Integer | 6379 | Redis server port |
Section: repos
This section groups Helix TeamHub repositories related settings.
Key | Type | Default | Description |
---|---|---|---|
backups
|
Boolean | false
|
Defines whether Helix TeamHub repository backups are enabled |
Section: unicorn_backend
This section groups Helix TeamHub backend (APIs, Helix TeamHub Admin) Unicorn server related settings.
Key | Type | Default | Description |
---|---|---|---|
backlog_socket | Integer | 64 | Unicorn socket backlog size |
worker_processes
|
Integer | 4
|
Number of Unicorn worker processes to start |
worker_timeout
|
Integer | 60
|
Number of seconds Unicorn worker times out |