tarampampam/3proxy repository overview

⁠

⁠Docker image with 3proxy⁠

3proxy⁠ is a tiny, battle-tested proxy server with 20+ years in production. It speaks HTTP/HTTPS, SOCKSv4/5, FTP, SMTP, supports IPv4/IPv6, DNS caching, ACLs, proxy chaining, load balancing, and a plugin system - all in a single lightweight binary, written in pure C.

This repository ships the stable version of 3proxy as a Docker image with a set of practical improvements over the vanilla upstream build:

• Environment-variable configuration - large set of options are exposed as an env vars; no config file needed, making it a proper container citizen from day one
• Scratch-based image - no OS, no package manager, no shell; just the binary and nothing else, minimizing the attack surface and image size
• Single static binary with bundled plugins - statically linked, key plugins included; zero shared-library dependencies, runs anywhere
• Styled error pages - proxy error responses come with a clean, dark-themed UI instead of the default spartan HTML
• dumb-init included - signals from Docker and other container runtimes are forwarded correctly; no orphaned child processes
• Built-in healthcheck - the container reports its own health to the runtime out of the box
• Lua entrypoint - startup logic lives in a readable Lua script, easy to extend without rebuilding
• Multi-arch images - amd64, arm64, arm/v7, ppc64le, s390x
• Pre-compiled releases - every GitHub release ships standalone 3proxy binaries for common OSes, ready to use without Docker
• Helm chart - production-ready chart with security-first defaults: non-root, minimal pod permissions, only what 3proxy actually needs granted by default
• Structured JSON logs - log output is JSON-formatted out of the box, ready to be ingested by any log aggregator without extra parsing
• No forwarding headers - the HTTP proxy runs in anonymous mode (-a): X-Forwarded-For and Via are never added, so the destination server sees a direct request rather than a proxied one

⁠🪂 Supported Environment Variables

⁠🚀 Installation

Download the latest binary for your OS/architecture from the releases page⁠, or use the Docker image:

Supported image architectures - linux/amd64, linux/arm/v7, linux/arm64, linux/ppc64le, linux/s390x. All images are signed with Cosign⁠ using keyless signing (GitHub OIDC).

Docker Image Content:

Permission     UID:GID       Size  Filetree
---------- -------------  -------  -----------------------------------
drwxr-xr-x         0:0     7.1 MB  ├── bin
-rwxr-xr-x         0:0     6.6 MB  │   ├── 3proxy
-rwxr-xr-x         0:0      64 kB  │   ├── dumb-init
-rwxr-xr-x         0:0     338 kB  │   ├── lua
-rwxr-xr-x         0:0      63 kB  │   └── portcheck
-rwxr-xr-x         0:0     8.9 kB  ├── entrypoint.lua
drwxr-xr-x         0:0     218 kB  ├── etc
drwxr-xr-x 10001:10001        0 B  │   ├── 3proxy
-rw-r--r--         0:0       16 B  │   ├── group
-rw-r--r--         0:0       49 B  │   ├── passwd
drwxr-xr-x         0:0     218 kB  │   └── ssl
drwxr-xr-x         0:0     218 kB  │       └── certs
-rw-r--r--         0:0     218 kB  │           └── ca-certificates.crt
drwxrwxrwt         0:0        0 B  └── tmp

⁠📦 Helm chart

A Helm chart for Kubernetes is included with each release (download⁠), published on Artifact Hub⁠, and also available via an OCI registry (Helm v3.8+ required):

helm install the3proxy \
  oci://ghcr.io/tarampampam/3proxy/charts/the3proxy \
  --version X.Y.Z

All supported chart values, examples, and usage instructions can be found at Artifact Hub⁠.

⁠🛠 Usage examples

⁠Open proxy (no authentication)

Starts HTTP and SOCKS5 proxies on their default ports with no credentials required. Anyone who can reach the ports can use the proxy, so only do this on a trusted/private network.

docker run --rm -d \
  -p "3128:3128/tcp" \
  -p "1080:1080/tcp" \
  ghcr.io/tarampampam/3proxy:2

⁠Protected proxy (login + password)

Enables basic username/password authentication. Requests without valid credentials receive 407 Proxy Authentication Required. Also sets a custom primary DNS resolver.

docker run --rm -d \
  -p "3128:3128/tcp" \
  -p "1080:1080/tcp" \
  -e "PROXY_LOGIN=user" \
  -e "PROXY_PASSWORD=secret" \
  -e "PRIMARY_RESOLVER=2001:4860:4860::8888" \
  ghcr.io/tarampampam/3proxy:2

⁠Docker Compose

Runs the proxy on custom ports with authentication and a higher connection limit. Because each connection needs two file descriptors, MAX_CONNECTIONS: 10000 requires ulimit nofile to be at least 20000.

services:
  3proxy:
    image: ghcr.io/tarampampam/3proxy:2
    environment:
      PROXY_LOGIN: evil
      PROXY_PASSWORD: live
      MAX_CONNECTIONS: 10000
      PROXY_PORT: 8080
      SOCKS_PORT: 1080
      PRIMARY_RESOLVER: 1.0.0.1
      SECONDARY_RESOLVER: 8.8.8.8
    ports:
      - '8080:8080/tcp'
      - '1080:1080/tcp'
    ulimits:
      nofile:
        soft: 20000
        hard: 20000

⁠⚙️ Advanced customization

⁠Custom 3proxy config file

If /etc/3proxy/3proxy.cfg exists when the container starts, the entrypoint skips config generation entirely and passes the file directly to 3proxy. All env-var settings are ignored in this case.

Docker CLI:

docker run --rm -d \
  -p "3128:3128/tcp" \
  -p "1080:1080/tcp" \
  -v "$(pwd)/3proxy.cfg:/etc/3proxy/3proxy.cfg:ro" \
  ghcr.io/tarampampam/3proxy:2

Docker Compose:

services:
  3proxy:
    image: ghcr.io/tarampampam/3proxy:2
    volumes:
      - ./3proxy.cfg:/etc/3proxy/3proxy.cfg:ro
    ports:
      - '3128:3128/tcp'
      - '1080:1080/tcp'

⁠Custom entrypoint script

The startup logic lives in /entrypoint.lua (a Lua 5.5 script). You can replace it by mounting your own file over that path, or by passing a different CMD.

Mount a custom Lua entrypoint (Docker CLI):

docker run --rm -d \
  -p "3128:3128/tcp" \
  -v "$(pwd)/my-entrypoint.lua:/entrypoint.lua:ro" \
  ghcr.io/tarampampam/3proxy:2

Override CMD with a script at an arbitrary path (Docker Compose):

services:
  3proxy:
    image: ghcr.io/tarampampam/3proxy:2
    volumes:
      - ./my-entrypoint.lua:/my-entrypoint.lua:ro
    command: ["/bin/lua", "/my-entrypoint.lua"]
    ports:
      - '3128:3128/tcp'

⁠🔧 Development

⁠Requirements

• docker⁠ for building and testing the Docker image locally
• Optional: helm⁠ + kind⁠ + docker for testing the Helm chart locally in Kubernetes
• Optional: helm-docs⁠ for generating Helm chart documentation

Commands:

# build the image locally
docker build --tag 3proxy:local .

# run the locally built image and smoke-test both proxies
docker run --rm -d --name 3proxy_local -p "3128:3128/tcp" -p "1080:1080/tcp" 3proxy:local
curl -sx http://localhost:3128 https://httpbin.org/ip  # HTTP proxy
curl -sx socks5://localhost:1080 https://httpbin.org/ip # SOCKS5 proxy
docker stop 3proxy_local

# lint the Helm chart
helm lint --strict ./deploy/helm

# regenerate Helm chart README from the template (requires helm-docs)
helm-docs -c ./deploy/helm/ -t README.tpl.md -o README.md

# test the Helm chart in a local kind cluster
kind create cluster --name 3proxy-dev
kind load docker-image 3proxy:local --name 3proxy-dev
helm install the3proxy ./deploy/helm \
  --set image.repository=3proxy --set image.tag=local \
  --set config.auth.login=user --set config.auth.password=secret \
  --wait
kubectl run smoke --image=curlimages/curl:latest --restart=Never --rm -i \
  -- curl --fail --proxy http://the3proxy:3128 --proxy-user user:secret https://httpbin.org/ip
kind delete cluster --name 3proxy-dev

⁠👾 Support

If you encounter any issues, please open an issue⁠ in this repository.

⁠📖 License

This project is licensed under the WTFPL. Use it freely and enjoy!