HomeGuidesChangelog
GuidesDiscussionChangelogLog In

Settings File

The settings file is used to configure a Team Server installation

The user settings file is a simple YAML file used to provide configuration values to the installer. At a minimum the fields shown below must be set. The full file and all possible values are provided in the section below.

admin_email: [email protected]
server:
  name: My Test Server
email:
  enabled: false
  • admin_email: This is the email address for an administrator responsible for the server. It is used for SSL certificate provisioning if using Let's Encrypt (notices will be sent to that address), and provided to users if they are blocked by the email allowlist.
  • server
    • name: Choose a short simple name to identify your server to your users. This will be shown on the log in button and Client UI. It should contain a-zA-Z0-9-_ and spaces only.
  • email
    • enabled: setting this to false disables outbound email sending. Outbound email is used to send password reset requests and email verification.

Settings File Contents

The full settings file with all possible fields is shown below.

admin_email: [email protected]
backup:
    directory: "s3:s3.amazonaws.com/bucket_name"
  service: "s3"
  connection: "/path/to/connection/file"
server:
  name: My Test Server
email:
  enabled: true
  email_from: "[email protected]"
  email_reply_to: "[email protected]"
  smtp_address: "smtp.example.com"
  smtp_port: 587
  smtp_authentication: "plain"
  smtp_enable_starttls_auto: true
  smtp_user_name: "username"
  smtp_password: "password"
  smtp_domain: "mycompany.com"
  require_verification: true
auth_provider:
  client_id: "client id"
  client_secret: "secret"
  oidc_wellknown_url: "https://auth.example.com"
  auth_url: "https://auth.example.com/oauth/authorize"
  token_url: "https://auth.example.com/oauth/access_token"
  profile_url: "https://api.example.com/user"
  logout_url: "https://auth.example.com/oauth/logout?redirect={{.Route}}"
ldap:
  host: "ldap.example.com:389"
  bindDN: "uid=serviceaccount,cn=users,dc=example,dc=com"
  bindPW: "password"
  usernamePrompt: "MyCompany Username"
  userSearch:
    baseDN: "cn=users,dc=example,dc=com"
    filter: "(objectClass=person)"
    username: "uid"
    idAttr: "uid"
    emailAttr: "mail"
    nameAttr: "name"
  groupSearch:
    baseDN: "cn=groups,dc=freeipa,dc=example,dc=com"
    filter: "(objectClass=group)"
    userMatchers:
    - userAttr: "uid"
      groupAttr: "member"
    nameAttr: "name"
external_object_store:
    enabled: true
  service: "s3"
  connection: "/path/to/connection/file"
  buckets:
    backup: "backup-bucket-name"
    tmp: "tmp-bucket-name"
    lfs: "lfs-bucket-name"
    packages: "packages-bucket-name"
    artifacts: "artifacts-bucket-name"
    uploads: "uploads-bucket-name"
    dataset: "dataset-bucket-name"
  • admin_email: This is the email address for an administrator responsible for the server. It is used for SSL certificate provisioning if using Let's Encrypt (notices will be sent to that address), and provided to users if they are blocked by the email allowlist.
  • backup: See Backup and Restore for details on how to use this section
    • directory: For local backups, the absolute path to the directory where backups will be stored. For external backups, the directory should be formatted as <service>:<url-to-restic-bucket>.
    • service: Only required if using external backups, current options include AWS S3 (s3).
    • connection: Only required if using external backups, current options include AWS S3 (example.s3.yaml).
  • server
    • name: Choose a short simple name to identify your server to your users. This will be shown on the log in button and Client UI. It should contain a-zA-Z0-9-_ and spaces only.
  • email
    • enabled: setting this to false disables outbound email sending. Setting it to true enables outbound email sending for things like password resets and email verification.
    • email_from: Email address to send from e.g. [email protected]
    • email_reply_to: Email address to reply to e.g. [email protected]
    • smtp_address: Address of the SMTP server
    • smtp_port: Port for the SMTP server
    • smtp_authentication: Type of authentication for the SMTP server ("login", "plain", false)
    • smtp_enable_starttls_auto: Enable STARTTLS (true or false)
    • smtp_user_name: Username for authenticating with the SMTP server
    • smtp_password: Password for authenticating with the SMTP server. Note: The password should not contain any String delimiters used in Ruby or YAML (f.e. ') to avoid unexpected behavior during the processing of config settings.
    • smtp_domain: sending domain for the SMTP server
    • require_verification: Option to require user's verify their email address before their account can be used to log in (true or false). If utilizing the email allowlist for limiting access to the server, you should set this to true. Note that when enabled, users will need to verify their email address, close the tab, and then re-open the client to log in.
  • auth_provider: See Authentication for details on how to use this section
    • client_id: Client ID configured in the auth provider.
    • client_secret: Client secret configured in the auth provider.
    • logout_url: (Optional) URL to call when the user logs out of the Team Server.
    • oidc_wellknown_url: (OIDC only) Base URL to where the OIDC .well-known data is located.
    • auth_url: (OAuth2 only) URL used to authenticate a user.
    • token_url: (OAuth2 only) URL used to get a user's access token.
    • profile_url: (OAuth2 only) URL used to get a user's profile.
  • ldap: See Authentication for details on how to use this section
    • host: Host and optional port of the LDAP server in the form host:port. If the port is not supplied, it will default to 636, the LDAP TLS port.
    • bindDN: The DN for the application service account. Used to search for users and groups and not required if the LDAP server provides access for anonymous auth.
    • bindPW: The password for the DN application service account.
    • usernamePrompt: The attribute to display in the provided password prompt. If unset, will display Username.
    • userSearch: User search maps a username and password entered by a user to a LDAP entry.
      • baseDN: BaseDN to start the search from. It will translate to the query (&(objectClass=person)(uid=<username>)).
      • filter: Optional filter to apply when searching the directory.
      • username: Username attribute used for comparing user entries. This will be translated and combined with the other filter as (<attr>=<username>).
      • idAttr: Direct mapping of the user entry attribute to the user's id.
      • emailAttr: Direct mapping of the user entry attribute to the user's email.
      • nameAttr: Direct mapping of the user entry attribute to the user's display name.
    • groupSearch: Group search queries for groups given a user entry.
      • baseDN: BaseDN to start the search from. It will translate to the query (&(objectClass=group)(member=<user uid>)).
      • filter: Optional filter to apply when searching the directory.
      • userMatchers: List container field pairs that are used to match a user to a group. It adds an additional requirement to the filter that an attribute in the group must match the user's attribute value.
      • nameAttr: Represents group name.
  • external_object_storage: See Object Storage for details on how to use this section
    • enabled: true if GitLab and dataset objects will be stored in external buckets, or false if they will be stored in local Minio buckets.
    • service: Only required if enabled: true, current options include AWS S3 (s3).
    • connection: Only required if enabled: true, current options include AWS S3 (example.s3.yaml).
    • buckets:
      • backup: Name of the bucket storing GitLab backup tars.
      • tmp: Name of the bucket storing GitLab temporary data.
      • lfs: Name of the bucket storing GitLab LFS files.
      • packages: Name of the bucket storing GitLab packages.
      • artifacts: Name of the bucket storing GitLab artifacts.
      • uploads: Name of the bucket storing GitLab uploads.
      • datasets: Name of the bucket storing dataset files.

Configuring Outbound Email

It is recommended that you use a programmatic email sending service such at Sendgrid or Mailgun, but most SMTP servers are supported. Example configurations for various providers can be found here.