Deploying Tinyproxy

Introduction

Tinyproxy is a lightweight HTTP/HTTPS proxy daemon designed for POSIX-based operating systems. Despite its small footprint, Tinyproxy provides powerful proxy functionality including access control, URL-based filtering, and transparent proxying capabilities. It’s the ideal choice when you need a fast, minimal proxy without the overhead of larger solutions.

Written in C with minimal dependencies, Tinyproxy is designed for speed and efficiency. It handles HTTP/1.1 features including CONNECT tunneling for HTTPS traffic, making it suitable for both HTTP and encrypted HTTPS proxying.

Key highlights of Tinyproxy:

• Extremely Lightweight: Small memory footprint (typically 2MB) and minimal CPU usage
• HTTP/HTTPS Support: Handles both HTTP proxying and HTTPS tunneling via CONNECT
• Access Control: IP-based allow/deny lists for connection filtering
• URL Filtering: Block or allow specific URLs and domains
• Anonymous Proxying: Remove identifying headers from requests
• Transparent Proxying: Support for transparent proxy configurations
• Upstream Proxy Support: Chain to other proxy servers
• Logging: Configurable access and error logging
• Simple Configuration: Single configuration file with clear syntax
• 100% Open Source: Licensed under GPL

This guide walks through deploying Tinyproxy on Klutch.sh using Docker, configuring access controls, and using the proxy for various purposes.

Why Deploy Tinyproxy on Klutch.sh

Deploying Tinyproxy on Klutch.sh provides several advantages:

Stable Proxy Endpoint: Get a reliable proxy server with consistent availability and performance.

Privacy Enhancement: Route traffic through a known server rather than untrusted networks.

Access Control: Restrict proxy access to specific IP addresses or authentication.

Development Tool: Test applications that need proxy support or simulate different network conditions.

GitHub Integration: Manage your proxy configuration through version control.

Minimal Resources: Tinyproxy’s efficiency means low resource costs on Klutch.sh.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and proxy concepts
• Knowledge of your client IP addresses for access control

Understanding Tinyproxy Architecture

Tinyproxy operates with a simple, efficient design:

Single Process: One process handles all connections using event-driven I/O.

HTTP Parsing: Full HTTP/1.1 protocol support with header manipulation capabilities.

CONNECT Tunneling: HTTPS traffic passes through using the CONNECT method, creating a tunnel.

Access Control Lists: IP-based filtering determines who can use the proxy.

Filter Files: Optional URL filtering for content control.

Preparing Your Repository

Create a GitHub repository with your Tinyproxy configuration.

Repository Structure

tinyproxy-deploy/
├── Dockerfile
├── tinyproxy.conf
├── filter.txt
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM alpine:3.18

# Install Tinyproxy
RUN apk add --no-cache tinyproxy

# Create directories
RUN mkdir -p /var/log/tinyproxy /var/run/tinyproxy

# Copy configuration files
COPY tinyproxy.conf /etc/tinyproxy/tinyproxy.conf
COPY filter.txt /etc/tinyproxy/filter.txt

# Set permissions
RUN chown -R nobody:nobody /var/log/tinyproxy /var/run/tinyproxy

# Expose proxy port
EXPOSE 8888

# Health check
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD wget --spider --proxy=off http://localhost:8888/stats || exit 1

# Run Tinyproxy in foreground
CMD ["tinyproxy", "-d", "-c", "/etc/tinyproxy/tinyproxy.conf"]

Creating the Configuration File

Create a tinyproxy.conf file:

##
## Tinyproxy Configuration
##

# User and Group to run as
User nobody
Group nobody

# Port to listen on
Port 8888

# Listen on all interfaces
Listen 0.0.0.0

# Connection timeout in seconds
Timeout 600

# Error log file
ErrorFile "/usr/share/tinyproxy/default.html"

# Stat page host for internal stats
StatHost "127.0.0.1"

# Log level: Critical, Error, Warning, Notice, Connect, Info
LogLevel Info

# PID file
PidFile "/var/run/tinyproxy/tinyproxy.pid"

# Maximum number of clients
MaxClients 100

# Minimum and maximum spare servers
MinSpareServers 5
MaxSpareServers 20

# Start servers
StartServers 10

# Maximum requests per child
MaxRequestsPerChild 0

# Allow connections from anywhere
# WARNING: Restrict this in production!
# Allow 127.0.0.1
# Allow 10.0.0.0/8
# Allow 192.168.0.0/16

# ViaProxyName - header value for Via header
ViaProxyName "tinyproxy"

# Disable Via header for anonymity
# DisableViaHeader Yes

Creating the Filter File

Create a filter.txt file for URL filtering (optional):

# URL Filter List
# One pattern per line, supports regex

# Block advertising domains
^ads\.
^tracking\.
doubleclick\.net
googlesyndication\.com

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store

Deploying Tinyproxy on Klutch.sh

Follow these steps to deploy your Tinyproxy instance:

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile tinyproxy.conf filter.txt .dockerignore README.md
git commit -m "Initial Tinyproxy configuration"
git remote add origin https://github.com/yourusername/tinyproxy-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Name it something like “proxy” or “tinyproxy”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Tinyproxy repository.

Configure TCP Traffic

Tinyproxy uses TCP for proxy connections. In the deployment settings:

• Select TCP as the traffic type
• Set the port to 8888

Attach Persistent Volumes (Optional)

For log persistence, add a volume:

Mount Path	Recommended Size	Purpose
/var/log/tinyproxy	1 GB	Access and error logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Build your Docker image
• Start the Tinyproxy service
• Configure TCP networking

Note Your Proxy Address

After deployment, note your server’s address and port from the Klutch.sh dashboard. This is what you’ll configure in your client applications.

Configuring Access Control

IP-Based Access Control

Restrict proxy access to specific IP addresses in tinyproxy.conf:

# Allow only specific IPs
Allow 203.0.113.50
Allow 198.51.100.0/24

# Allow a range
Allow 10.0.0.0/8

Open Access Warning

If you leave access unrestricted, anyone who discovers your proxy can use it. Always configure access controls for production deployments.

Using the Proxy

Browser Configuration

Configure your browser to use the proxy:

Firefox:

1. Settings > Network Settings > Settings
2. Select “Manual proxy configuration”
3. Enter your Tinyproxy server address and port 8888
4. Check “Use this proxy for HTTPS”

Chrome (via system settings):

1. Settings > System > Open your computer’s proxy settings
2. Configure your system proxy to point to Tinyproxy

Command Line Usage

Use environment variables for command-line tools:

export HTTP_PROXY="http://your-proxy.klutch.sh:8888"
export HTTPS_PROXY="http://your-proxy.klutch.sh:8888"

# Test with curl
curl -x http://your-proxy.klutch.sh:8888 https://httpbin.org/ip

Programming Languages

Python (requests):

import requests

proxies = {
    'http': 'http://your-proxy.klutch.sh:8888',
    'https': 'http://your-proxy.klutch.sh:8888',
}

response = requests.get('https://httpbin.org/ip', proxies=proxies)
print(response.json())

Node.js (axios):

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

const agent = new HttpsProxyAgent('http://your-proxy.klutch.sh:8888');

axios.get('https://httpbin.org/ip', { httpsAgent: agent })
    .then(response => console.log(response.data));

URL Filtering

Enabling Filtering

Enable URL filtering in tinyproxy.conf:

# Enable filter file
Filter "/etc/tinyproxy/filter.txt"

# Default to allow (filter acts as blacklist)
FilterDefaultDeny No

# Filter based on full URLs
FilterURLs On

# Use extended regex
FilterExtended On

Filter Patterns

Add patterns to filter.txt:

# Block all subdomains of example.com
.*\.example\.com

# Block specific path
example\.com/ads

# Block by file extension
.*\.exe$

# Block advertising networks
googlesyndication\.com
doubleclick\.net

Anonymous Proxying

Removing Identifying Headers

Configure Tinyproxy to strip identifying headers:

# Remove identifying headers
Anonymous "Host"
Anonymous "Authorization"
Anonymous "Referer"
Anonymous "User-Agent"
Anonymous "Cookie"
Anonymous "From"

# Disable Via header
DisableViaHeader Yes

Performance Tuning

Connection Settings

Adjust for your usage patterns:

# Increase for high-traffic scenarios
MaxClients 200
MinSpareServers 10
MaxSpareServers 50
StartServers 20

# Reduce timeout for faster failure detection
Timeout 300

Resource Recommendations

Concurrent Users	RAM	CPU
1-10	64 MB	0.25 vCPU
10-50	128 MB	0.5 vCPU
50-200	256 MB	1 vCPU

Troubleshooting Common Issues

Connection Refused

Symptoms: Clients cannot connect to the proxy.

Solutions:

• Verify TCP port 8888 is configured in Klutch.sh
• Check that Listen 0.0.0.0 is set in config
• Confirm the container is running
• Review access control rules

Slow Performance

Symptoms: Requests take too long.

Solutions:

• Reduce filter complexity
• Increase MaxClients
• Check upstream proxy if configured
• Review resource allocation

HTTPS Not Working

Symptoms: HTTPS sites fail through proxy.

Solutions:

• Tinyproxy uses CONNECT for HTTPS - verify it’s not blocked
• Check that both HTTP and HTTPS proxy are configured the same
• Some applications need explicit HTTPS proxy configuration

Security Considerations

Production Hardening

For production deployments:

1. Always restrict access: Never run an open proxy
2. Monitor access logs: Watch for unusual patterns
3. Regular updates: Keep Tinyproxy updated for security patches

Additional Resources

• Official Tinyproxy Website
• Tinyproxy GitHub Repository
• Example Configuration
• Klutch.sh Deployments

Conclusion

Tinyproxy on Klutch.sh provides a lightweight, efficient proxy solution for various use cases. Whether you need a development proxy for testing, a privacy-enhancing gateway, or a content filter, Tinyproxy delivers the functionality without the overhead of larger proxy solutions.

The combination of Tinyproxy’s minimal resource requirements and Klutch.sh’s reliable infrastructure means you get a stable proxy endpoint with low operational costs. Configuration through GitHub enables version control of your proxy settings and easy updates through redeployment.

Remember to always configure appropriate access controls and understand the responsibilities that come with running a proxy server.