squid-proxy-tailscale

Run a Squid HTTP/HTTPS proxy that is only reachable via your Tailscale VPN.
Tailscale runs as a sidecar container and provides the network namespace; Squid binds to port 3128 inside that namespace, so the proxy is never exposed on the public internet.

---

Quick Start

# 1. Clone the repo
git clone https://github.com/ez4-dev/squid-proxy-tailscale.git
cd squid-proxy-tailscale

# 2. Create your environment file and set your Tailscale auth key
cp .env.example .env
# Edit .env – at minimum set TS_AUTHKEY
#   TS_AUTHKEY=YOUR_TAILSCALE_AUTH_KEY_HERE

# 3. Start both containers
docker compose up -d

# 4. Check that the Tailscale node is authenticated and connected
docker exec tailscale tailscale status

# 5. Get the Tailscale IP of this node
docker exec tailscale tailscale ip -4

Configure any device on your tailnet to use the proxy:

export http_proxy=http://<tailscale-ip>:3128
export https_proxy=http://<tailscale-ip>:3128

---

Environment Variables

Copy .env.example to .env and fill in the values before starting.

Variable	Required	Default	Description
TS_AUTHKEY	Yes	–	Tailscale auth key. Generate at https://login.tailscale.com/admin/settings/keys
TS_HOSTNAME	No	squid-proxy	Hostname advertised on your tailnet
SQUID_USERNAME	No	proxy	Username for Squid basic authentication (see below)
SQUID_PASSWORD	No	changeme	Password for Squid basic authentication (see below)

---

Enabling Basic Authentication (optional)

By default Squid allows any device on your tailnet without a password.
To require credentials:

# 1. Create the htpasswd file inside the squid container
docker compose exec squid htpasswd -bc /etc/squid/htpasswd "$SQUID_USERNAME" "$SQUID_PASSWORD"

# 2. Uncomment the auth block in squid.conf (lines starting with auth_param / acl authenticated)

# 3. Reload Squid
docker compose exec squid squid -k reconfigure

Then use the proxy with credentials:

export http_proxy=http://<username>:<password>@<tailscale-ip>:3128
export https_proxy=http://<username>:<password>@<tailscale-ip>:3128

---

Useful Commands

# View live proxy logs
docker compose logs -f squid

# View Tailscale logs
docker compose logs -f tailscale

# Stop all services
docker compose down

# Stop and remove volumes (clears Tailscale state and Squid cache)
docker compose down -v

# Restart a single service
docker compose restart squid

---

Project Structure

.
├── docker-compose.yml   # Service definitions (tailscale + squid)
├── squid.conf           # Squid configuration (mounted read-only)
├── .env.example         # Environment variable template
└── .gitignore