Standalone Redis using the Linux package

The Linux package can be used to configure a standalone Redis server. In this configuration, Redis is not scaled, and represents a single point of failure. However, in a scaled environment the objective is to allow the environment to handle more users or to increase throughput. Redis itself is generally stable and can handle many requests, so it is an acceptable trade off to have only a single instance. See the reference architectures page for an overview of GitLab scaling options.

Set up the standalone Redis instance

The steps below are the minimum necessary to configure a Redis server with the Linux package:

1. SSH into the Redis server.

2. Download and install the Linux package you want by using steps 1 and 2 from the GitLab downloads page. Do not complete any other steps on the download page.

3. Edit /etc/gitlab/gitlab.rb and add the contents:

   ## Enable Redis and disable all other services
   ## https://docs.gitlab.com/omnibus/roles/
   roles ['redis_master_role']
   
   ## Redis configuration
   redis['bind'] = '0.0.0.0'
   redis['port'] = 6379
   redis['password'] = '<redis_password>'
   
   ## Disable automatic database migrations
   ## Only the primary GitLab application server should handle migrations
   gitlab_rails['auto_migrate'] = false

4. Reconfigure GitLab for the changes to take effect.

5. Note the Redis node’s IP address or hostname, port, and Redis password. These are necessary when configuring the GitLab application servers.

Advanced configuration options are supported and can be added if needed.

Set up the GitLab Rails application instance

On the instance where GitLab is installed:

1. Edit the /etc/gitlab/gitlab.rb file and add the following contents:

   ## Disable Redis
   redis['enable'] = false
   
   gitlab_rails['redis_host'] = 'redis.example.com'
   gitlab_rails['redis_port'] = 6379
   
   ## Required if Redis authentication is configured on the Redis node
   gitlab_rails['redis_password'] = '<redis_password>'

2. Save your changes to /etc/gitlab/gitlab.rb.

3. Reconfigure GitLab for the changes to take effect.

Use Valkey instead of Redis

You can use Valkey as a drop-in replacement for Redis. Valkey uses the same configuration options as Redis.

Using Valkey instead of Redis is a beta feature.

To use Valkey instead of Redis on a standalone node:

1. Edit /etc/gitlab/gitlab.rb and add the contents:

   ## Enable Redis and disable all other services
   ## https://docs.gitlab.com/omnibus/roles/
   roles ['redis_master_role']
   
   ## Switch to Valkey
   redis['backend'] = 'valkey'
   
   ## Redis configuration
   redis['bind'] = '0.0.0.0'
   redis['port'] = 6379
   redis['password'] = '<redis_password>'
   
   ## Disable automatic database migrations
   gitlab_rails['auto_migrate'] = false

2. Reconfigure GitLab for the changes to take effect.

The GitLab Rails application configuration remains the same. Configure gitlab_rails['redis_host'], gitlab_rails['redis_port'], and gitlab_rails['redis_password'] as you would for Redis.

Known issues

• Because of known issue 589642, the Admin Area reports the Valkey version incorrectly. This issue doesn’t affect the version of Valkey installed or how it functions.

Troubleshooting

See the Redis troubleshooting guide.