Configuración de proxy en contenedores Docker: guía completa con ejemplos de código

Los contenedores Docker a menudo requieren acceso a recursos externos a través de un proxy: para scraping, pruebas desde diferentes regiones o eludir restricciones. Una configuración incorrecta del proxy puede llevar a errores de conexión, filtraciones de IP real y fallos en el funcionamiento de las aplicaciones. En este artículo, analizaremos todas las formas de configurar un proxy en Docker: desde variables de entorno simples hasta escenarios avanzados con docker-compose y redes personalizadas.

¿Por qué se necesitan proxies en contenedores Docker?

Los contenedores Docker se utilizan en diversos escenarios donde los proxies se vuelven una necesidad. Analicemos las principales tareas que resuelven los proxies en aplicaciones contenedorizadas.

Scraping y recolección de datos: Si ejecutas scrapers en contenedores Docker para recolectar datos de marketplaces (Wildberries, Ozon), redes sociales o motores de búsqueda, los proxies protegen contra bloqueos por IP. Los contenedores permiten escalar el scraping: ejecutar de 10 a 50 instancias simultáneamente, cada una con su propio proxy.

Pruebas desde diferentes regiones: Al desarrollar aplicaciones web o APIs móviles, a menudo es necesario verificar cómo funciona el servicio desde diferentes países. Los contenedores Docker con proxies de diferentes geolocalizaciones permiten automatizar tales pruebas en un pipeline CI/CD.

Automatización y bots: Los contenedores con Selenium, Puppeteer o Playwright para automatización de navegadores requieren proxies para trabajar con múltiples cuentas. Cada contenedor recibe su proxy y un entorno aislado.

Eludir restricciones corporativas: En algunas infraestructuras, los contenedores Docker deben pasar por un proxy corporativo para acceder a Internet. Sin una configuración adecuada, los contenedores no podrán descargar paquetes o acceder a APIs externas.

Configuración básica a través de variables de entorno

La forma más sencilla de configurar un proxy en un contenedor Docker es pasar variables de entorno al iniciar. Este método funciona para la mayoría de las aplicaciones que respetan las variables estándar HTTP_PROXY, HTTPS_PROXY y NO_PROXY.

Ejecutar un contenedor con proxy a través de docker run:

docker run -d \
  -e HTTP_PROXY="http://username:password@proxy.example.com:8080" \
  -e HTTPS_PROXY="http://username:password@proxy.example.com:8080" \
  -e NO_PROXY="localhost,127.0.0.1,.local" \
  your-image:latest

Explicación de los parámetros:

• HTTP_PROXY — proxy para solicitudes HTTP
• HTTPS_PROXY — proxy para solicitudes HTTPS (usa http://, no https://)
• NO_PROXY — lista de direcciones que no deben pasar por el proxy

Ejemplo con proxy SOCKS5:

docker run -d \
  -e HTTP_PROXY="socks5://username:password@proxy.example.com:1080" \
  -e HTTPS_PROXY="socks5://username:password@proxy.example.com:1080" \
  your-image:latest

Configuración del proxy para el daemon de Docker (afecta a todos los contenedores):

Si necesitas que todos los contenedores utilicen un proxy por defecto, configura el daemon de Docker. Crea un archivo /etc/systemd/system/docker.service.d/http-proxy.conf:

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,.local"

Después de realizar cambios, reinicia Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Configuración del proxy en Dockerfile

Cuando construyes una imagen Docker que necesita descargar paquetes a través de un proxy (por ejemplo, apt-get, pip, npm), es necesario configurar el proxy en la etapa de construcción. Docker soporta argumentos de tiempo de construcción para esto.

Ejemplo de Dockerfile con soporte para proxy:

FROM python:3.11-slim

# Argumentos para el proxy (se pasan durante la construcción)
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Establecer variables de entorno para la construcción
ENV HTTP_PROXY=${HTTP_PROXY}
ENV HTTPS_PROXY=${HTTPS_PROXY}
ENV NO_PROXY=${NO_PROXY}

# Instalación de dependencias a través del proxy
RUN apt-get update && apt-get install -y curl

# Instalación de paquetes de Python
COPY requirements.txt .
RUN pip install --proxy ${HTTP_PROXY} -r requirements.txt

# Copiar la aplicación
COPY . /app
WORKDIR /app

# Eliminar variables de proxy para runtime (opcional)
ENV HTTP_PROXY=
ENV HTTPS_PROXY=

CMD ["python", "app.py"]

Construcción de la imagen pasando el proxy:

docker build \
  --build-arg HTTP_PROXY=http://proxy.example.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.example.com:8080 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  -t my-app:latest .

Para aplicaciones Node.js (npm a través de proxy):

FROM node:18-alpine

ARG HTTP_PROXY
ARG HTTPS_PROXY

# Configuración de npm para trabajar a través de proxy
RUN npm config set proxy ${HTTP_PROXY}
RUN npm config set https-proxy ${HTTPS_PROXY}

COPY package*.json ./
RUN npm install

# Limpiar configuraciones de proxy para npm
RUN npm config delete proxy
RUN npm config delete https-proxy

COPY . .
CMD ["node", "server.js"]

Configuración del proxy en docker-compose.yml

Docker Compose simplifica la gestión de proxies para aplicaciones de múltiples contenedores. Puedes configurar proxies globalmente o para servicios individuales.

Configuración básica con proxy para un solo servicio:

version: '3.8'

services:
  parser:
    image: python:3.11-slim
    environment:
      - HTTP_PROXY=http://username:password@proxy.example.com:8080
      - HTTPS_PROXY=http://username:password@proxy.example.com:8080
      - NO_PROXY=localhost,127.0.0.1,db
    volumes:
      - ./app:/app
    working_dir: /app
    command: python parser.py
    
  db:
    image: postgres:15
    # La base de datos no utiliza proxy
    environment:
      - POSTGRES_PASSWORD=secret

Uso de un archivo .env para almacenar credenciales de forma segura:

Crea un archivo .env en el directorio con docker-compose.yml:

PROXY_URL=http://username:password@proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1

Referencia las variables en docker-compose.yml:

version: '3.8'

services:
  parser:
    image: python:3.11-slim
    environment:
      - HTTP_PROXY=${PROXY_URL}
      - HTTPS_PROXY=${PROXY_URL}
      - NO_PROXY=${NO_PROXY}
    volumes:
      - ./app:/app
    working_dir: /app
    command: python parser.py

Configuración del proxy para la construcción de la imagen en docker-compose:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - HTTP_PROXY=${PROXY_URL}
        - HTTPS_PROXY=${PROXY_URL}
        - NO_PROXY=${NO_PROXY}
    environment:
      - HTTP_PROXY=${PROXY_URL}
      - HTTPS_PROXY=${PROXY_URL}
    ports:
      - "3000:3000"

Escalado con diferentes proxies para cada instancia:

Si necesitas ejecutar varios scrapers, cada uno con su propio proxy, utiliza servicios separados:

version: '3.8'

services:
  parser-1:
    image: my-parser:latest
    environment:
      - PROXY_URL=http://user:pass@proxy1.example.com:8080
    volumes:
      - ./data:/data
    
  parser-2:
    image: my-parser:latest
    environment:
      - PROXY_URL=http://user:pass@proxy2.example.com:8080
    volumes:
      - ./data:/data
    
  parser-3:
    image: my-parser:latest
    environment:
      - PROXY_URL=http://user:pass@proxy3.example.com:8080
    volumes:
      - ./data:/data

Configuración del proxy a nivel de aplicación

Algunas aplicaciones no soportan las variables de entorno estándar HTTP_PROXY. En tales casos, es necesario configurar el proxy en el código de la aplicación o en archivos de configuración.

Python (biblioteca requests):

import os
import requests

# Obtener el proxy de la variable de entorno
proxy_url = os.getenv('PROXY_URL', 'http://proxy.example.com:8080')

proxies = {
    'http': proxy_url,
    'https': proxy_url
}

# Usar el proxy en las solicitudes
response = requests.get('https://api.example.com/data', proxies=proxies)
print(response.json())

# Para proxy SOCKS5 instala pip install requests[socks]
# proxies = {
#     'http': 'socks5://user:pass@proxy.example.com:1080',
#     'https': 'socks5://user:pass@proxy.example.com:1080'
# }

Python (aiohttp para solicitudes asíncronas):

import os
import aiohttp
import asyncio

async def fetch_with_proxy():
    proxy_url = os.getenv('PROXY_URL')
    
    async with aiohttp.ClientSession() as session:
        async with session.get(
            'https://api.example.com/data',
            proxy=proxy_url
        ) as response:
            data = await response.json()
            print(data)

asyncio.run(fetch_with_proxy())

Node.js (biblioteca axios):

const axios = require('axios');
const { HttpsProxyAgent } = require('https-proxy-agent');

const proxyUrl = process.env.PROXY_URL || 'http://proxy.example.com:8080';
const agent = new HttpsProxyAgent(proxyUrl);

axios.get('https://api.example.com/data', {
  httpsAgent: agent
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error:', error.message);
});

Node.js (módulo https integrado):

const https = require('https');
const { HttpsProxyAgent } = require('https-proxy-agent');

const proxyUrl = process.env.PROXY_URL;
const agent = new HttpsProxyAgent(proxyUrl);

const options = {
  hostname: 'api.example.com',
  port: 443,
  path: '/data',
  method: 'GET',
  agent: agent
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => data += chunk);
  res.on('end', () => console.log(JSON.parse(data)));
});

req.on('error', (error) => console.error(error));
req.end();

Selenium con proxy en un contenedor Docker:

from selenium import webdriver
from selenium.webdriver.common.proxy import Proxy, ProxyType
import os

proxy_url = os.getenv('PROXY_URL', 'proxy.example.com:8080')

# Configuración del proxy para Chrome
chrome_options = webdriver.ChromeOptions()
chrome_options.add_argument(f'--proxy-server={proxy_url}')

# Para autenticación usa una extensión o túnel SSH
driver = webdriver.Chrome(options=chrome_options)
driver.get('https://example.com')
print(driver.title)
driver.quit()

Puppeteer con proxy:

const puppeteer = require('puppeteer');

(async () => {
  const proxyUrl = process.env.PROXY_URL || 'proxy.example.com:8080';
  
  const browser = await puppeteer.launch({
    args: [`--proxy-server=${proxyUrl}`],
    headless: true
  });
  
  const page = await browser.newPage();
  
  // Autenticación para el proxy
  await page.authenticate({
    username: 'your-username',
    password: 'your-password'
  });
  
  await page.goto('https://example.com');
  console.log(await page.title());
  
  await browser.close();
})();

Qué tipo de proxy elegir para Docker

La elección del tipo de proxy depende de la tarea que tu aplicación esté resolviendo en el contenedor Docker. Analicemos los principales escenarios y recomendaciones.

Recomendaciones para elegir para tareas específicas:

Scraping de marketplaces y catálogos de productos: Si estás scrapeando Wildberries, Ozon u otros marketplaces a través de contenedores Docker, utiliza proxies residenciales. Estas plataformas bloquean activamente las IPs de datacenter. Configura la rotación de proxies cada 5-10 minutos para simular diferentes usuarios.

Pruebas de API y desarrollo: Para probar tus propias APIs o integraciones con servicios externos, son adecuados los proxies de datacenter. Proporcionan alta velocidad y estabilidad de conexión, lo que es importante para pruebas automatizadas en CI/CD.

Automatización con Selenium/Puppeteer: Al ejecutar automatización de navegador en contenedores para trabajar con sitios seguros (redes sociales, bancos, aplicaciones web complejas), elige proxies residenciales. Reducen la probabilidad de captchas y bloqueos.

Pruebas geodistribuidas: Si necesitas verificar la disponibilidad del servicio desde diferentes países, utiliza proxies residenciales con selección de geolocalización específica. Ejecuta varios contenedores Docker, cada uno con su proxy de su país.

Resolución de problemas comunes

Al trabajar con proxies en contenedores Docker, surgen problemas comunes. Analicemos los más frecuentes y cómo resolverlos.

Problema 1: El contenedor no puede conectarse al proxy

Síntomas: Errores "Connection refused", "Proxy connection failed", timeouts al iniciar el contenedor.

Soluciones:

• Verifica la disponibilidad del proxy desde el host: curl -x http://proxy:port https://example.com
• Asegúrate de que el servidor proxy sea accesible desde la red Docker. Si el proxy está en localhost del host, utiliza host.docker.internal (Mac/Windows) o la IP del host en la red bridge
• Verifica las reglas del firewall: los contenedores Docker pueden estar bloqueados para conexiones salientes
• Para proxies con autenticación, verifica la corrección del nombre de usuario y la contraseña, escapa los caracteres especiales en la URL

Ejemplo de acceso al proxy en el host:

# Mac/Windows
docker run -e HTTP_PROXY=http://host.docker.internal:8080 my-image

# Linux (averigua la IP del host en la red bridge)
ip addr show docker0  # Normalmente 172.17.0.1
docker run -e HTTP_PROXY=http://172.17.0.1:8080 my-image

Problema 2: DNS no se resuelve a través del proxy

Síntomas: Errores "Could not resolve host", las solicitudes DNS no pasan a través del proxy.

Soluciones:

• Utiliza un proxy SOCKS5 en lugar de HTTP: SOCKS5 proxy DNS requests
• Configura DNS en Docker: agrega --dns 8.8.8.8 al iniciar el contenedor
• Para aplicaciones que no soportan DNS a través del proxy, utiliza proxychains dentro del contenedor

# Dockerfile con proxychains
FROM python:3.11-slim

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

# Configuración de proxychains
RUN echo "strict_chain\nproxy_dns\n[ProxyList]\nsocks5 proxy.example.com 1080" > /etc/proxychains4.conf

# Ejecutar la aplicación a través de proxychains
CMD ["proxychains4", "python", "app.py"]

Problema 3: Filtración de la IP real del contenedor

Síntomas: El servicio objetivo ve la IP del host o del contenedor en lugar de la IP del proxy.

Soluciones:

• Verifica que la aplicación realmente esté utilizando el proxy: haz una solicitud a https://api.ipify.org
• Asegúrate de que todos los clientes HTTP en el código estén configurados para usar el proxy
• Para conexiones WebRTC y WebSocket, el proxy puede no funcionar: desactiva WebRTC en los navegadores
• Verifica los encabezados de las solicitudes: algunas bibliotecas agregan X-Forwarded-For con la IP real

Prueba de filtración de IP en el contenedor:

# Sin proxy
docker run --rm curlimages/curl:latest curl https://api.ipify.org

# Con proxy
docker run --rm \
  -e HTTPS_PROXY=http://proxy.example.com:8080 \
  curlimages/curl:latest curl https://api.ipify.org

Problema 4: Funcionamiento lento a través del proxy

Síntomas: Altas latencias, timeouts, carga lenta de datos.

Soluciones:

• Verifica la velocidad del proxy directamente desde el host: puede que el problema esté en el propio proxy
• Aumenta los timeouts en la aplicación para trabajar con proxies lentos
• Utiliza conexiones keep-alive para reutilizar conexiones TCP
• Para proxies residenciales, una velocidad lenta es normal: optimiza la cantidad de solicitudes
• Configura un pool de conexiones en los clientes HTTP para solicitudes paralelas

Problema 5: El proxy funciona para HTTP, pero no para HTTPS

Síntomas: Las solicitudes HTTP pasan, HTTPS devuelven errores SSL/TLS.

Soluciones:

• Asegúrate de que la variable HTTPS_PROXY esté establecida (no solo HTTP_PROXY)
• Utiliza http:// en la URL del proxy para HTTPS_PROXY, no https://
• Verifica si el proxy soporta el método CONNECT para el tunelado HTTPS
• Para proxies con certificados autofirmados, desactiva la verificación SSL (¡solo para pruebas!)

Seguridad y gestión de credenciales

Almacenar credenciales de proxy en contenedores Docker requiere especial atención a la seguridad. Una gestión inadecuada de contraseñas puede llevar a su filtración en registros, imágenes o repositorios.

Utiliza Docker Secrets para producción:

Docker Swarm soporta un mecanismo de secrets para el almacenamiento seguro de contraseñas. Crea un secret:

echo "http://username:password@proxy.example.com:8080" | docker secret create proxy_url -

Utiliza en docker-compose para Swarm:

version: '3.8'

services:
  app:
    image: my-app:latest
    secrets:
      - proxy_url
    environment:
      - PROXY_URL_FILE=/run/secrets/proxy_url
    command: sh -c 'export HTTP_PROXY=$(cat $$PROXY_URL_FILE) && python app.py'

secrets:
  proxy_url:
    external: true

Variables de entorno a través de archivos (.env):

Para desarrollo, utiliza archivos .env, pero NUNCA los commits en Git. Agrega a .gitignore:

# .gitignore
.env
.env.local
*.env

Crea .env.example sin credenciales reales:

# .env.example
PROXY_URL=http://username:password@proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1

Evita hardcodear credenciales en imágenes:

# ❌ MALO - la contraseña permanecerá en la imagen
FROM python:3.11
ENV HTTP_PROXY=http://user:secretpass@proxy.com:8080
COPY . /app

# ✅ BUENO - pasa a través de argumentos de construcción o variables de runtime
FROM python:3.11
ARG HTTP_PROXY
# Se utiliza solo durante la construcción, no se guarda en la imagen final

Utiliza construcciones multi-stage para limpiar credenciales:

# Etapa de construcción con proxy
FROM python:3.11 AS builder
ARG HTTP_PROXY
ENV HTTP_PROXY=${HTTP_PROXY}
COPY requirements.txt .
RUN pip install -r requirements.txt

# Etapa final sin variables de proxy
FROM python:3.11-slim
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY . /app
WORKDIR /app
CMD ["python", "app.py"]

Rotación de credenciales de proxy:

Si tu proveedor de proxy soporta API para generar credenciales temporales, utilízalas en lugar de contraseñas estáticas. Crea un script de inicialización en el contenedor:

#!/bin/bash
# entrypoint.sh

# Obtener credenciales temporales de la API
PROXY_CREDS=$(curl -s https://api.proxyservice.com/generate-temp-auth)
export HTTP_PROXY="http://${PROXY_CREDS}@proxy.example.com:8080"

# Ejecutar la aplicación
exec python app.py

Registro sin filtración de contraseñas:

Configura el registro para que las variables con el proxy no aparezcan en la salida:

import os
import re

def safe_log_env():
    """Registro de variables de entorno sin contraseñas"""
    for key, value in os.environ.items():
        if 'PROXY' in key:
            # Enmascarar la contraseña en la URL
            safe_value = re.sub(r'://([^:]+):([^@]+)@', r'://\1:****@', value)
            print(f"{key}={safe_value}")
        else:
            print(f"{key}={value}")

safe_log_env()

Conclusión

Configurar un proxy en contenedores Docker es una habilidad importante para los desarrolladores que trabajan con scraping, automatización y sistemas distribuidos. Has aprendido cómo configurar proxies a través de variables de entorno, Dockerfile y docker-compose, cómo integrar proxies en el código de aplicaciones en Python y Node.js, y cómo resolver problemas comunes de conexión y seguridad.

Puntos clave para un trabajo exitoso con proxies en Docker: utiliza variables de entorno para flexibilidad, almacena credenciales de forma segura a través de secrets o archivos .env, elige el tipo de proxy según la tarea, y siempre prueba la ausencia de filtraciones de IP real antes de lanzar en producción.

Para la mayoría de las tareas de scraping y automatización en contenedores Docker, recomendamos utilizar proxies residenciales — proporcionan alta anonimidad y un riesgo mínimo de bloqueos al trabajar con sitios seguros y APIs. Si necesitas la máxima velocidad para pruebas de API o tareas internas, considera los proxies de datacenter.