Skip to content
Klutch.sh Docs

Deploying g3proxy

Introduction

g3proxy is a high-performance forward proxy server developed by ByteDance. It provides enterprise-grade proxy capabilities with support for HTTP, HTTPS, SOCKS5, and transparent proxying. Built with Rust, g3proxy offers exceptional performance and memory safety.

The project is designed for large-scale deployments and includes features like access control, traffic logging, connection pooling, and upstream proxy chaining. It is particularly well-suited for organizations needing reliable proxy infrastructure.

Key highlights of g3proxy:

  • Multi-Protocol Support: HTTP, HTTPS, SOCKS4, SOCKS5 protocols
  • High Performance: Built with Rust for speed and efficiency
  • Access Control: User authentication and IP-based access rules
  • Proxy Chaining: Chain multiple upstream proxies
  • Connection Pooling: Efficient connection reuse
  • TLS Interception: Optional HTTPS inspection
  • Traffic Logging: Detailed request and response logging
  • Health Checking: Automatic upstream health monitoring
  • Load Balancing: Distribute traffic across upstreams
  • Metrics: Prometheus-compatible metrics export
  • Open Source: Licensed under Apache 2.0

This guide walks through deploying g3proxy on Klutch.sh using Docker.

Why Deploy g3proxy on Klutch.sh

Deploying g3proxy on Klutch.sh provides several advantages:

Global Access: Provide proxy services from cloud infrastructure.

Reliable Uptime: Cloud hosting ensures consistent availability.

Scalable: Handle varying traffic loads with resource adjustment.

Secure: HTTPS encryption for proxy communications.

Monitoring: Integrate with metrics and logging systems.

Prerequisites

Before deploying g3proxy on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Understanding of proxy concepts and configuration
  • Basic familiarity with Docker and YAML configuration

Understanding g3proxy Architecture

g3proxy has a modular architecture:

Server: Listens for client connections and handles protocol negotiation.

Escaper: Manages outbound connections to target hosts or upstream proxies.

User Authentication: Validates user credentials against configured backends.

Access Control: Enforces rules for allowed destinations and operations.

Audit: Logs traffic for monitoring and compliance.

Preparing Your Repository

Create a GitHub repository with your g3proxy configuration.

Repository Structure

g3proxy-deploy/
├── Dockerfile
├── config/
│   ├── main.yaml
│   └── server.yaml
└── .dockerignore

Creating the Dockerfile

FROM rust:alpine AS builder


RUN apk add --no-cache musl-dev openssl-dev


# Clone and build g3proxy
RUN cargo install g3proxy


FROM alpine:latest


RUN apk add --no-cache ca-certificates openssl


COPY --from=builder /usr/local/cargo/bin/g3proxy /usr/local/bin/g3proxy


# Create config directory
RUN mkdir -p /etc/g3proxy


# Copy configuration
COPY config/ /etc/g3proxy/


# Expose proxy ports
EXPOSE 8080 1080


# Run g3proxy
CMD ["g3proxy", "-c", "/etc/g3proxy/main.yaml"]

Main Configuration

Create config/main.yaml:

log:
  default:
    level: info


server:
  - name: http_proxy
    type: http_proxy
    listen: 0.0.0.0:8080
    escaper: direct


  - name: socks_proxy
    type: socks_proxy
    listen: 0.0.0.0:1080
    escaper: direct


escaper:
  - name: direct
    type: direct_fixed
    resolver: system


resolver:
  - name: system
    type: c-ares

Environment Variables Reference

VariableRequiredDescription
G3PROXY_CONFIGNoPath to configuration file
G3PROXY_LOG_LEVELNoLogging level (debug, info, warn, error)

Deploying g3proxy on Klutch.sh

    Prepare Configuration

    Create your g3proxy configuration files with appropriate settings for your use case.

    Push Your Repository to GitHub

    Commit your Dockerfile and configuration to GitHub.

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “g3proxy” or “forward-proxy”.

    Create a New App

    Create a new app and connect your GitHub repository.

    Configure Network Ports

    Configure the required ports:

    • Port 8080 for HTTP proxy
    • Port 1080 for SOCKS5 proxy

    Set Environment Variables

    Add any required configuration:

    VariableValue
    G3PROXY_LOG_LEVELinfo

    Deploy Your Application

    Click Deploy to build and launch g3proxy.

    Test Proxy Connection

    Test the proxy using curl:

    Terminal window
    curl -x https://your-app.klutch.sh:8080 https://httpbin.org/ip

Configuration Options

HTTP Proxy Server

Configure HTTP/HTTPS proxy:

server:
  - name: http_proxy
    type: http_proxy
    listen: 0.0.0.0:8080
    escaper: direct
    auth:
      type: basic
      users:
        - user: myuser
          pass: mypassword

SOCKS5 Proxy Server

Configure SOCKS5 proxy:

server:
  - name: socks_proxy
    type: socks_proxy
    listen: 0.0.0.0:1080
    escaper: direct
    auth:
      type: password
      users:
        - user: myuser
          pass: mypassword

Upstream Proxy Chaining

Route traffic through upstream proxies:

escaper:
  - name: upstream
    type: proxy_http
    proxy_addr: upstream-proxy.example.com:3128
    auth:
      type: basic
      user: upstream_user
      pass: upstream_pass

Access Control

Restrict allowed destinations:

server:
  - name: http_proxy
    type: http_proxy
    listen: 0.0.0.0:8080
    escaper: direct
    acl:
      - action: deny
        dst_host: "*.internal.example.com"
      - action: allow
        dst_host: "*"

Authentication Methods

Basic Authentication

Username and password authentication:

auth:
  type: basic
  users:
    - user: user1
      pass: password1
    - user: user2
      pass: password2

No Authentication

Allow anonymous access:

auth:
  type: none

Logging and Monitoring

Log Configuration

Configure logging output:

log:
  default:
    level: info
    format: json
  audit:
    level: info
    path: /var/log/g3proxy/audit.log

Metrics Export

Enable Prometheus metrics:

stat:
  prometheus:
    listen: 0.0.0.0:9090
    path: /metrics

Use Cases

Corporate Proxy

Provide internet access through a controlled proxy:

  • User authentication
  • Access logging
  • Destination filtering

Web Scraping

Route scraping requests through proxy:

  • IP rotation with upstream proxies
  • Connection pooling
  • Rate limiting

Development Testing

Test applications with proxy configuration:

  • Inspect HTTP traffic
  • Simulate network conditions
  • Test proxy authentication

Security Best Practices

Enable Authentication

Always require authentication for production deployments:

auth:
  type: basic
  users:
    - user: secure_user
      pass: strong_password

Restrict Access

Limit who can connect:

acl:
  src_ip:
    - action: allow
      ip: 10.0.0.0/8
    - action: deny
      ip: "*"

Use TLS

Enable TLS for proxy connections when possible.

Troubleshooting

Connection Refused

  • Verify proxy is listening on correct port
  • Check firewall rules
  • Confirm network configuration

Authentication Failures

  • Verify username and password
  • Check authentication configuration
  • Review authentication logs

Upstream Connection Issues

  • Test upstream proxy connectivity
  • Verify upstream credentials
  • Check DNS resolution

Additional Resources

Conclusion

Deploying g3proxy on Klutch.sh provides a high-performance proxy solution for various use cases. Whether you need corporate proxy services, web scraping infrastructure, or development testing, g3proxy’s comprehensive features and Rust-based performance make it an excellent choice.

The combination of g3proxy’s enterprise features and Klutch.sh’s reliable hosting creates a robust platform for proxy services.