Setting Up GitLab Behind An Nginx Reverse Proxy A Comprehensive Guide

Jul 16, 2025 by ADMIN 70 views

How to Set Up GitLab Behind an Nginx Reverse Proxy

Setting up a reverse proxy for GitLab using Nginx is a common practice for enhancing security, improving performance, and simplifying access management. This comprehensive guide will walk you through the process step-by-step, ensuring that even if you're new to GitLab or reverse proxies, you'll be able to configure your system effectively. We will cover the prerequisites, the configuration of both GitLab and Nginx, and troubleshooting common issues. By the end of this article, you'll have a robust setup that allows you to access your GitLab instance securely and efficiently.

Understanding Reverse Proxies and Their Benefits

Before diving into the configuration, it's crucial to understand what a reverse proxy is and why it's beneficial for GitLab. A reverse proxy sits in front of one or more web servers, intercepting client requests. It then forwards these requests to the appropriate server and returns the server's response to the client. This setup offers several advantages:

Security: A reverse proxy can hide the internal structure of your network, making it more difficult for attackers to target specific servers. It can also act as a buffer against attacks, such as DDoS, by filtering malicious traffic before it reaches your GitLab instance.
Load Balancing: Reverse proxies can distribute client requests across multiple servers, preventing any single server from becoming overloaded. This improves the overall performance and availability of your GitLab instance.
SSL Termination: The reverse proxy can handle SSL encryption and decryption, freeing up the GitLab server to focus on application logic. This also simplifies certificate management, as you only need to install the SSL certificate on the reverse proxy.
Caching: Reverse proxies can cache static content, such as images and stylesheets, reducing the load on the GitLab server and improving response times.
Centralized Access Control: A reverse proxy allows you to implement centralized access control policies, ensuring that only authorized users can access your GitLab instance.

Prerequisites

Before you begin, ensure you have the following prerequisites in place:

GitLab Instance: You should have a GitLab instance up and running. This guide assumes you have a basic GitLab installation. If not, refer to the official GitLab documentation for installation instructions.
Nginx: Nginx should be installed on your server. If it's not, you can install it using your distribution's package manager. For example, on Ubuntu, you can use sudo apt-get install nginx.
Domain Name (Optional): While not strictly required, it's highly recommended to have a domain name pointed to your server's IP address. This allows you to access GitLab via a memorable URL (e.g., gitlab.example.com) instead of an IP address.
SSL Certificate (Optional): For secure access, you should have an SSL certificate for your domain. You can obtain a free certificate from Let's Encrypt or purchase one from a commercial provider.
Root or Sudo Access: You'll need root or sudo privileges to configure Nginx and GitLab.

Step-by-Step Configuration

Step 1: Configure GitLab

First, you need to configure GitLab to work behind a reverse proxy. This involves setting the external_url and other related settings in the GitLab configuration file. The configuration file is typically located at /etc/gitlab/gitlab.rb.

Open the GitLab Configuration File: Use a text editor with root privileges to open the file:
```
sudo nano /etc/gitlab/gitlab.rb
```
Set the external_url: Find the external_url setting and set it to the URL you want to use to access GitLab. For example:
```
external_url 'http://gitlab.example.com'
```
If you're using HTTPS, make sure to use https:// in the URL:
```
external_url 'https://gitlab.example.com'
```
Configure Nginx Settings: GitLab has built-in Nginx settings that you can adjust. Uncomment and modify the following settings as needed:
```
nginx['enable'] = false # Disable the built-in Nginx
# nginx['listen_port'] = 80 # If you want to listen on a different port
# nginx['listen_https'] = true # If you are using HTTPS
# nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.example.com.crt" # Path to your SSL certificate
# nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.example.com.key" # Path to your SSL key
```
Since we are setting up an external Nginx reverse proxy, we disable the built-in Nginx by setting nginx['enable'] = false. If you are using HTTPS, you can specify the paths to your SSL certificate and key. However, in this guide, we will configure SSL termination on the external Nginx.
Save and Close the File: Save the changes and close the text editor.
Reconfigure GitLab: Apply the changes by running the reconfigure command:
```
sudo gitlab-ctl reconfigure
```
This command will apply the new settings and restart GitLab.

Step 2: Configure Nginx as a Reverse Proxy

Next, you need to configure Nginx to act as a reverse proxy for GitLab. This involves creating a new Nginx configuration file for your GitLab instance.

Create a New Nginx Configuration File: Create a new configuration file in the /etc/nginx/conf.d/ directory. For example:
```
sudo nano /etc/nginx/conf.d/gitlab.conf
```
Configure the Nginx Server Block: Add the following configuration to the file, adjusting the settings as needed:
```
server {
    listen 80;
    server_name gitlab.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name gitlab.example.com;

    ssl_certificate /etc/nginx/ssl/gitlab.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/gitlab.example.com.key;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    proxy_read_timeout 300;
    proxy_connect_timeout 300;
    proxy_redirect off;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header X-Nginx-Proxy true;
        proxy_set_header Connection "";
        proxy_buffering off;
    }

    # Additional settings for GitLab
    location /uploads/ {
        client_max_body_size 50m;
    }

    location ~ /api/v[0-9]+/ {
        proxy_pass http://127.0.0.1:8080;
    }

    location /cable {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }

    location ~ /.well-known {
        allow all;
    }

    access_log /var/log/nginx/gitlab_access.log;
    error_log /var/log/nginx/gitlab_error.log;
}
```
Let's break down this configuration:
- listen 80; and listen 443 ssl http2;: These lines specify that Nginx should listen on port 80 (HTTP) and port 443 (HTTPS). The http2 directive enables HTTP/2 for improved performance.
- server_name gitlab.example.com;: This sets the server name to your domain.
- return 301 https://$host$request_uri;: This line redirects all HTTP requests to HTTPS.
- ssl_certificate and ssl_certificate_key: These lines specify the paths to your SSL certificate and key.
- ssl_protocols and ssl_ciphers: These lines configure SSL protocols and ciphers for secure communication.
- proxy_read_timeout and proxy_connect_timeout: These lines set timeouts for reading and connecting to the upstream server.
- proxy_pass http://127.0.0.1:8080;: This is the core of the reverse proxy configuration. It tells Nginx to forward requests to the GitLab server running on 127.0.0.1:8080. GitLab typically runs on port 8080 by default.
- proxy_set_header: These lines set various headers that are passed to the GitLab server. These headers are important for GitLab to function correctly behind a reverse proxy. The X-Real-IP, X-Forwarded-For, and X-Forwarded-Proto headers convey information about the client's IP address and the protocol used. The Host header ensures that GitLab knows the correct hostname.
- location /uploads/: This block configures settings for file uploads, increasing the client_max_body_size to 50MB.
- location ~ /api/v[0-9]+/: This block configures proxy settings for the GitLab API.
- location /cable: This block configures proxy settings for GitLab ActionCable, which is used for real-time features.
- location ~ /.well-known: This block allows access to the .well-known directory, which is used for Let's Encrypt certificate validation.
- access_log and error_log: These lines specify the paths to the access and error logs.
Create SSL Certificates (if needed): If you don't have SSL certificates, you can generate them using Let's Encrypt. For example:
```
sudo apt-get update
sudo apt-get install certbot python3-certbot-nginx
sudo certbot --nginx -d gitlab.example.com
```
This command will automatically obtain and install SSL certificates for your domain.
Save and Close the File: Save the changes and close the text editor.
Test the Nginx Configuration: Before restarting Nginx, test the configuration for syntax errors:
```
sudo nginx -t
```
If there are no errors, you should see:
```
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
```
If there are errors, review your configuration file and correct them.
Restart Nginx: Apply the changes by restarting Nginx:
```
sudo systemctl restart nginx
```

Step 3: Verify the Setup

Now that you've configured GitLab and Nginx, it's time to verify the setup.

Access GitLab in Your Browser: Open your web browser and navigate to your GitLab URL (e.g., https://gitlab.example.com).
Check for Errors: If everything is configured correctly, you should see the GitLab login page. If you encounter any errors, check the Nginx and GitLab logs for clues.
- Nginx logs are typically located at /var/log/nginx/access.log and /var/log/nginx/error.log.
- GitLab logs are typically located in the /var/log/gitlab/ directory.
Log In: Try logging in to your GitLab instance. If you can log in and navigate the interface, your setup is working correctly.

Troubleshooting Common Issues

Even with careful configuration, you might encounter issues. Here are some common problems and their solutions:

502 Bad Gateway: This error typically indicates that Nginx cannot connect to the GitLab server. Check the following:
- GitLab is Running: Ensure that GitLab is running by using the command sudo gitlab-ctl status. If it's not running, start it with sudo gitlab-ctl start.
- Firewall: Make sure that your firewall is not blocking traffic between Nginx and GitLab. If you have a firewall enabled, you might need to allow traffic on port 8080.
- Nginx Configuration: Double-check your Nginx configuration for errors, especially the proxy_pass directive. Ensure that it points to the correct address and port (http://127.0.0.1:8080).
Infinite Redirect Loop: This issue often occurs when the external_url in gitlab.rb is not configured correctly or when the Nginx configuration is missing the necessary proxy_set_header directives. Ensure that the external_url matches the URL you are using to access GitLab and that the Nginx configuration includes the following lines:
```
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;
```
SSL Certificate Issues: If you encounter SSL certificate errors, such as