Configuration

This document describes how you can configure your GDK environment.

• Git configuration.
• GDK configuration.
• Runner settings.
• Vite settings.
• Webpack settings.
• ActionCable settings.
• Grafana settings.
• Tool version manager settings.
• IDE settings.
• Environment variables.

Git configuration

Git has features which are disabled by default, and would be great to enable to be more effective with Git. Run rake git:configure to set the recommendations for some repositories within the GDK.

To set the configuration globally, run rake git:configure[true]. When using zsh, don’t forget to escape the square brackets: rake git:configure\[true\].

GDK configuration

GDK can be configured using gdk.yml configuration file.

gdk.yml

You can override the GDK default settings with a gdk.yml in the GDK root, which is the only supported configuration method.

To see available configuration settings, see gdk.example.yml.

This file contains all possible settings with example values. Note that these values may not be the default that GDK uses.

If you want to check which settings are in place, you can run rake dump_config, which prints all applied settings in a YAML structure.

• Notable settings
• GDK settings
• GitLab settings
• GitLab Docs settings
• Additional projects settings
• NGINX settings

Run GitLab and GitLab FOSS concurrently

To have multiple GDK instances running concurrently, for example to test GitLab and GitLab FOSS, initialize each into a separate GDK folder. To run them simultaneously, make sure they don’t use conflicting port numbers.

For example, to start GDK ports at 5000 instead of the default 3000:

1. Run gdk config set port_offset 5000 to update gdk.yml.
2. Run gdk rake claimed_ports to verify the change.
3. Run gdk reconfigure to apply the configuration changes.

Now, GDK runs on port 5000, workhorse on 5007 etc.

Overwriting configuration files

Any configuration file managed by GDK is overwritten whenever there are changes in its source (a .example or .erb file). When GDK overwrites a configuration file it moves the original file into the .backups subdirectory of your GDK installation.

If you have local changes that you don’t want GDK to touch you can protect individual configuration files. For example:

# in gdk.yml
gdk:
  protected_config_files:
  - 'gitaly/*.toml'

Notable settings

Here are a few settings worth mentioning:

For example, to change the port GDK is accessible on, you can set this in your gdk.yml:

port: 3001

And run the following command to apply the change:

gdk reconfigure

GDK settings

There are also a few settings that configure the behavior of GDK itself:

Experimental GDK settings

Experimental settings may be promoted to stable settings or they may be deprecated.

Hooks

Before and after hooks are supported for gdk start, gdk stop, and gdk update.

A common use for GDK hooks is removing uncommitted changes to gitlab/db/structure.sql, or truncating the Rails logs in gitlab/log.

Use precompiled Ruby binaries

You can configure GDK to use precompiled Ruby binaries when updating to newer versions of Ruby instead of compiling from source. Precompiled binaries are available for most Ruby versions and can reduce Ruby installation time from minutes to seconds.

When binaries aren’t available for your specific version, GDK automatically falls back to compiling from source code.

To set GDK to use precompiled Ruby binaries to install new versions:

gdk config set gdk.use_precompiled_ruby true

To return to compiling new versions of Ruby from source code:

gdk config set gdk.use_precompiled_ruby false

GitLab settings

Rails

Rails background jobs (Sidekiq)

Skip compile

For some software, it’s possible to download the pre-compiled binaries instead of compiling them.

GitLab Docs settings

Under the docs_gitlab_com key, you can define the following settings:

For more information on using GitLab Docs with GDK, see the GitLab Docs how to.

Snowplow Micro

Under the snowplow_micro key, you can define the following settings:

Additional projects settings

You can have GDK manage checkouts for these projects:

• gitlab-runner
• gitlab-pages
• omnibus-gitlab
• charts/gitlab
• cloud-native/gitlab-operator

Under the gitlab_runner key, you can define the following settings:

Under the gitlab_pages key, you can define the following settings:

For further details check the Contribute to GitLab Pages development documentation.

Under the omnibus_gitlab key, you can define the following settings:

Under the charts_gitlab key, you can define the following settings:

Under the gitlab_operator key, you can define the following settings:

NGINX settings

See configuring NGINX for a comprehensive guide.

Configuration precedence

GDK uses the following order of precedence when selecting the configuration method to use:

• gdk.yml
• Default value

Reading the configuration

To print settings from the configuration you can use gdk config get <setting>.

More information on the available gdk commands is found in GDK commands.

Implementation detail

Here are some details on how the configuration management is built. You can continue reading, or watch the deep-dive recorded by Toon.

GDK::ConfigSettings

This is the base class and the engine behind the configuration management. It defines a DSL to configure GDK.

Most of the magic happens through the class method .method_missing. The implementation of this method dynamically defines instance methods for configuration settings.

Below is an example subclass of GDK::ConfigSettings to demonstrate each kind.

class ExampleConfig < GDK::ConfigSettings
  foo 'hello'
  bar { rand(1..10) }
  fuz do |f|
    f.buz 1234
  end
end

• foo: (literal value) This is just a literal value, it can be any type (for example, Number, Boolean, String).
• bar: (block without argument) This is using a block to set a value. It evaluates the Ruby code to dynamically calculate a value.
• fuz: (block with argument) When the block takes a single argument, it expects you are setting child settings.

If you’d dump this configuration with rake dump_config, you get something like:

foo: hello
bar: 5
fuz:
  buz: 1234

When you use a block without argument you can also calculate a value based on another setting. So for example, we’d could replace the bar block with { config.fuz.buz + 1000 } and then the value would be 2234.

GDK::Config

GDK::Config is the single source of truth when it comes down to defaults. In this file, every existing setting is specified and for each setting a default is provided.

Dynamic settings

Some settings in GDK::Config are prepended with __ (double underscore). These are not supposed to be set in gdk.yml and only act as a intermediate value. They also are not shown by #dump!.

Adding a setting

When you add a new setting:

1. Add it to lib/gdk/config.rb.
2. Run rake gdk.example.yml to regenerate this file.
3. Commit both files.

Runner settings

Under the runner key you can define the following settings for the GitLab Runner:

Vite settings

Vite offers an improved developer experience by default.

Vite compiles JavaScript and Vue files quickly and only as requested. Vite also consumes less memory.

These improvements are possible because Vite uses esbuild under the hood. For more details on the implementation of Vite at GitLab, see the RFC frontend/rfcs#106.

If you are using Vite, please leave feedback of your experience. There are some known caveats, they are linked to the feedback issue. Please make sure to check those. There are two caveats worth calling out:

1. vite serves files directly, so ad blockers might block them based on their name. The workaround is to turn ad blockers off for the GDK.
2. vite on Linux watches a lot of files, so you might need to raise the max_watch_files limit.

To enable Vite for your GDK:

1. Ensure that your gdk is up to date (gdk update)

2. Ensure the gdk is running with webpack.

3. If you ran vite manually before, make sure no process remains.

4. Run the following commands to set up Vite:

   gdk stop webpack rails-web
   gdk config set webpack.enabled false
   gdk config set vite.enabled true
   gdk reconfigure
   gdk restart vite rails-web

To disable Vite, run the following commands:

gdk stop vite rails-web
gdk config set vite.enabled false
gdk config set webpack.enabled true
gdk reconfigure
gdk restart webpack rails-web

Vite gdk.yml settings

Webpack settings

The GDK ships with vite support. Consider trying it for a better developer experience.

Webpack gdk.yml settings

Under the webpack key you can define the following settings with their defaults:

webpack:
  enabled: true
  host: 127.0.0.1
  port: 3808
  static: false
  vendor_dll: false
  incremental: true
  incremental_ttl: 30
  allowed_hosts: []

Incremental webpack compilation

By default, webpack only compiles page bundles for pages that were visited within the last webpack.incremental_ttl days. This is done to keep the memory consumption of the webpack development server low. If you visit a previously unvisited page or one visited longer than webpack.incremental_ttl days ago, you see an overlay informing you that the page is being compiled. A page reload (either manually or via live_reload) then ensures the correct assets are served.

You can change the number of days that page bundles are considered “recent”, and should be eagerly compiled. This number represents the trade-off between lazy/eager compilation versus low/high memory consumption of the webpack development server. A higher number means fewer pages needing to be compiled on demand, at the cost of higher memory consumption. A lower number means lower memory consumption, at the cost of more pages being compiled on demand. A value of 0 means that all pages in your history, regardless of how long ago you visited them, are eagerly compiled.

For instance, if you visited a particular page webpack.incremental_ttl - 1 days ago, it would render as normal if you visited it today. But, if instead you visit it tomorrow, you would see an initial “compiling” overlay.

The history of previously visited pages is stored in the WEBPACK_CACHE_PATH directory. Clearing this directory will lose that history, meaning subsequent page visits will trigger on demand compilation. Over time, your history will be rebuilt.

To disable incremental compilation entirely and always eagerly compile all page bundles, set webpack.incremental: false in your gdk.yml.

Saving memory on the webpack development server

GDK defaults to mostly memory-intensive settings. GDK uses the webpack development server, which watches file changes and keeps all the frontend assets in memory. This allows for very fast recompilation.

An alternative is to lower the memory requirements of GDK. This is useful for back-end development or where GDK is running in lower-memory environments. To lower the memory requirements of GDK:

• Set webpack.static: true in your gdk.yml. All frontend assets are compiled once when GDK starts and again from scratch if any front-end source or dependency file changes. For example, when switching branches.
• Set webpack.vendor_dll: true in your gdk.yml. This mode is an alternate memory saving mode, which takes infrequently updated dependencies and combines them into one long-lived bundle that is written to disk and does not reside in memory. You may see 200 to 300 MB in memory savings.
• Reduce the value of webpack.incremental_ttl in your gdk.yml. This means fewer page bundles will be eagerly compiled.

This means you pay a high upfront cost of a single memory- and CPU-intensive compile. However, if you do not change any frontend files, you just have a lightweight Ruby server running.

If you experience any problems with one of the modes, you can quickly change the settings in your gdk.yml and regenerate the Procfile:

gdk reconfigure

Webpack allowed hosts

By default, webpack only accepts requests with a Host header that matches the GDK hostname. This is a secure default. But sometimes you may want webpack to accept requests from other known hosts.

The webpack.allowed_hosts setting takes an array of strings, for example ["gdk2.test", "gdk3.test"].

When webpack.allowed_hosts is not explicitly configured in gdk.yml, it defaults to gitlab.rails.allowed_hosts. In that case, the configuration flow is:

  graph LR
  A["gdk.yml<br>(gitlab.rails.allowed_hosts)"]

  subgraph Template
  B["gitlab.yml.erb<br>(gitlab.allowed_hosts)"]
  C["Procfile.erb<br>(DEV_SERVER_ALLOWED_HOSTS)"]
  end

  A --> B
  A --> C

  subgraph Generated
  D["gitlab.yml<br>(gitlab.allowed_hosts)"]
  E["Procfile<br>(DEV_SERVER_ALLOWED_HOSTS)"]
  end

  B -- gdk reconfigure --> D
  C --> E

  subgraph Runsv
  F[rails-web]
  G["webpack<br>(allowedHosts)"]
  end

  D -- gdk start --> F
  E --> G

Example

As an example:

• Your GDK hostname is gdk.test.
• You are running another GDK locally as a Geo secondary site with hostname set to gdk2.test.

As a result, web requests against gdk2.test reference webpack URLs for gdk2.test at the same port as the primary webpack. Web requests are made to the same port because the Geo secondary site proxies most web requests to the primary site and so the primary site renders the webpack links.

The Host of the original request is propagated to the primary site, and the primary site renders URLs with that Host. However, the primary site has no way of knowing if the secondary site is running webpack at a different port. You can’t run two webpack servers locally, listening on the same port for different hosts.

So what options do you have to make this work? You can either:

• Run your gdk2.test site on a different IP.

• Let the gdk2.test webpack requests reach the primary site’s webpack server. The requests would get blocked by default, and then you could unblock them with webpack.allowed_hosts setting.

  In this case, you would already set gitlab.rails.allowed_hosts to ["gdk2.test"]. This is why webpack.allowed_hosts defaults to gitlab.rails.allowed_hosts.

Webpack environment variables

The GitLab application exposes various configuration options for webpack via environment variables. These can be modified to improve performance or enable debugging.

These settings can be configured using env.runit.

ActionCable settings

Under the action_cable key you can define the following settings with their defaults:

action_cable:
  worker_pool_size: 4

Grafana settings

Under the grafana key you can define the following settings with their defaults:

grafana:
  enabled: false
  port: 4000

Tool version manager settings

Under the tool_version_manager key you can define the following settings with their defaults:

tool_version_manager:
  enabled: true

IDE settings

To get alias completion and type hinting in the gitlab project, you need to create a jsconfig.json file. See Type hinting aliases.

Environment variables

Due to how runit manages processes, environment variables must be configured through GDK’s configuration system.

Setting environment variables

All environment variables must be set in gdk.yml:

env:
  VARIABLE_NAME_1: "value1"
  VARIABLE_NAME_2: "value2"

After updating gdk.yml, apply the changes:

gdk restart

Note: You can optionally run gdk reconfigure before restarting if you want to regenerate configuration files, but it’s not required for environment variable changes.

Important notes

• Temporary environment variables are not supported. Using export in your shell will not affect GDK services due to runit process isolation.
• The env.runit file is deprecated (see issue #2133).
• All environment variables must be configured in gdk.yml.
• Always run gdk restart after changing environment variables.
• Environment variables are visible to all child processes. Store credentials in separate files or dedicated settings in gdk.yml instead.