Running GitLab behind a HTTP proxy (Squid)

Intro

If you run GitLab in Docker on a host that must route outbound HTTP/HTTPS traffic through a (Squid) proxy, you need to configure the OS, Docker daemon, container environment and GitLab itself. Below are the working configuration snippets I used and important considerations.

This guide assumes your Squid proxy is reachable at proxy:3128 from the GitLab host/container network.

1. System environment (Debian)

Make the proxy available to all processes on the host by exporting the environment variables in /etc/environment so services and systemd units can pick them up:

export http_proxy="http://proxy:3128"
export HTTP_PROXY="${http_proxy}"
export https_proxy="http://proxy:3128"
export HTTPS_PROXY="${https_proxy}"

After editing, either reboot or re-source the environment for the running shells/services. Note that some services (systemd units) require Environment= in their unit files or a system-wide drop-in to pick up these vars.

2. Docker daemon

Tell the Docker daemon to use the proxy so pulls and other daemon-level operations go through Squid. Add or edit /etc/docker/daemon.json:

{
  "proxies": {
    "http-proxy": "http://proxy:3128",
    "https-proxy": "http://proxy:3128"
  }
}

Reload and restart Docker after changing this file:

sudo systemctl daemon-reload
sudo systemctl restart docker

3. docker-compose / container environment

Containers also need the proxy variables so processes inside the container use the proxy for outbound requests. In docker-compose.yml I set the environment for the GitLab service:

services:
  gitlab-ee:
    environment:
      - no_proxy=localhost
      - http_proxy=http://proxy:3128
      - https_proxy=http://proxy:3128
      - HTTP_PROXY=http://proxy:3128
      - HTTPS_PROXY=http://proxy:3128

Notes:

• Include both lowercase and uppercase variants (http_proxy and HTTP_PROXY) because some programs read only one of the two.
• Add no_proxy for local addresses you want to bypass the proxy.

4. GitLab configuration (gitlab.rb)

GitLab's runtime (Puma, Sidekiq, Rails) can also pick up environment variables from gitlab_rails['env']. I added:

gitlab_rails['env'] = {
  "http_proxy" => "http://proxy:3128",
  "https_proxy" => "http://proxy:3128",
  "no_proxy" => "localhost",
}

After updating gitlab.rb run the normal reconfigure/restart steps for your installation (for Omnibus Docker setups this typically means recreating the container or running the reconfigure inside the container if applicable).

5. Testing and verification

• Check that the host can reach the internet through Squid:

curl -v -I http://example.com
curl -v -I https://example.com

• From inside the GitLab container, verify the environment and outbound requests:

docker compose exec gitlab-ee bash
env | grep -i proxy
curl -v -I http://example.com
curl -v -I https://example.com

• Inspect Docker daemon logs if pulls are failing: sudo journalctl -u docker -e.

6. Common issues & considerations

• no_proxy inaccuracies: Add all internal domains, registry hosts and metadata endpoints (e.g., localhost,127.0.0.1,gitlab.example.com,registry.gitlab.com) to no_proxy to avoid routing local or service-to-service traffic through Squid.

7. Restart and apply

After making the above changes restart Docker and your compose stack.

sudo systemctl restart docker
docker compose down
docker compose up -d

Optionally restart the host or re-login to pick up /etc/environment in shells.

Tips and troubleshooting

• If you encounter issues with local services (e.g., GitLab Runner, registry, etc.) not being reachable, double-check your no_proxy settings and ensure that the proxy is not intercepting local traffic.
• If you have a firewall or network restrictions, ensure that the GitLab host/container can reach the Squid proxy and that the proxy allows the necessary outbound traffic.

Problems?

If you find mistakes or have suggestions, let me know. If you encounter problems, check if the proxy is actually being used by the host and container processes, and verify the no_proxy settings for local addresses. Also, make sure the Squid proxy allows the necessary traffic and is reachable from the GitLab host/container network (firewall, DNS, etc.).