RoProxy
Back to all posts
Configuring HTTP Proxies Inside Docker Containers
docker proxy networking

Configuring HTTP Proxies Inside Docker Containers

November 5, 2026

Why Configure Proxies in Docker Containers

Containers are isolated by default, but they still need outbound network access. A build step may download packages from a public registry. A running application may call external APIs. If the host sits behind a corporate proxy or you route traffic through a proxy gateway, the container does not automatically inherit those settings. Without explicit configuration, apt-get, npm, and HTTP clients inside the container fail with connection timeouts or DNS errors.

This guide covers how to pass proxy settings into Docker containers at build time and runtime, how to verify that traffic actually leaves through the proxy, and how to keep local traffic from being proxied by mistake.

Build-Time vs Runtime Proxy Settings

Docker treats proxy configuration in two distinct places:

  • Build time: environment variables available during docker build. These affect RUN commands such as package installation.
  • Runtime: environment variables available when the container starts. These affect the application and any outbound requests it makes after launch.

Setting one does not set the other. If your container needs to install packages and then call an API, you usually need both.

Build-Time Configuration

Use ARG and ENV in the Dockerfile. Pass values with docker build --build-arg.

ARG HTTP_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
ARG HTTPS_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
ARG NO_PROXY=localhost,127.0.0.1,.local

ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

RUN apt-get update && apt-get install -y curl

Build the image:

docker build \
  --build-arg HTTP_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT \
  --build-arg HTTPS_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT \
  -t my-app .

The ARG values are not persisted in the final image unless you copy them into ENV. The ENV lines above make them available to RUN and to later stages.

Runtime Configuration

Pass the same variables when you start the container. The application inside can read them directly, or your language runtime may pick them up automatically.

docker run -e HTTP_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT \
  -e HTTPS_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT \
  -e NO_PROXY=localhost,127.0.0.1 \
  my-app

With Compose:

services:
  app:
    build: .
    environment:
      - HTTP_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
      - HTTPS_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
      - NO_PROXY=localhost,127.0.0.1,.local

RoProxy sessions connect through a gateway host on an HTTP port. If you use RoProxy, put that gateway host and port in place of GATEWAY_HOST and HTTP_PORT.

Verifying the Exit IP

Before trusting the configuration, confirm that the container reaches the internet through the proxy and not directly. The simplest check is to ask an echo service for the public IP.

Inside the container, or through docker exec:

curl https://api.ipify.org?format=json

To force the request through the proxy from your host:

curl -x http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT \
  https://api.ipify.org?format=json

Compare the returned IP address with your host's direct IP. If they match, the proxy is not being used. If they differ, traffic is going through the gateway.

If you get a connection error, check that the gateway host is reachable from the container network and that the credentials are correct.

NO_PROXY and Internal Traffic

Not every outbound request should go through a proxy. Requests to local services, linked containers, or instance metadata endpoints should usually bypass it. Otherwise, the proxy may try to reach an internal address that it cannot route to, causing timeouts.

Add exceptions to NO_PROXY:

NO_PROXY=localhost,127.0.0.1,.local,host.docker.internal,.svc.cluster.local

Compose example:

environment:
  - NO_PROXY=localhost,127.0.0.1,.local,host.docker.internal

A common mistake is proxying traffic to a database running on the same host. If localhost is not in NO_PROXY, the application sends the connection to the proxy gateway, which likely has no route back to your local database.

Complete Example: Node.js Container

Here is a full Dockerfile and Compose file for a Node.js application that installs dependencies at build time and calls an external API at runtime.

FROM node:20-alpine

ARG HTTP_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
ARG HTTPS_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
ARG NO_PROXY=localhost,127.0.0.1

ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY
ENV NO_PROXY=$NO_PROXY

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .

CMD node index.js

services:
  app:
    build: .
    environment:
      - HTTP_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
      - HTTPS_PROXY=http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT
      - NO_PROXY=localhost,127.0.0.1

Some Node.js HTTP clients read proxy variables automatically; others require you to pass the proxy URL explicitly. Check your library's documentation if outbound requests still fail after setting the environment.

Conclusion

Proxy settings in Docker are not inherited from the host. You must pass them explicitly at build time for package installation and at runtime for application traffic. Always verify with curl https://api.ipify.org?format=json, and always exclude local addresses with NO_PROXY. With those three steps, containerized apps can reach external services reliably through an HTTP gateway.

RoProxy sessions can serve as that gateway, with each session using its own username and password. Rotate the session IP through the API when you need a new address, then continue running containers without changing their proxy configuration.