From 13b66aeea6ec9dfacffb34943bb6089498ad557c Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Fri, 29 May 2026 11:55:16 +0800 Subject: [PATCH] docs: add LAN socks5 compose deployment --- .env.example | 11 +++++-- .gitignore | 3 ++ README.hermes.md | 49 ++++++++++++++++++++++++++++++++ docker-compose.ipvlan-linux.yml | 26 +++++++++++++++++ docker-compose.macvlan-linux.yml | 26 +++++++++++++++++ docker-compose.yml | 18 ++++++++---- 6 files changed, 125 insertions(+), 8 deletions(-) create mode 100644 .gitignore create mode 100644 README.hermes.md create mode 100644 docker-compose.ipvlan-linux.yml create mode 100644 docker-compose.macvlan-linux.yml diff --git a/.env.example b/.env.example index 8946001..fa74716 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,9 @@ -PROXY_USER=someuser -PROXY_PASSWORD=somepass +# Authentication is enabled by default. Change these before production use. +REQUIRE_AUTH=true +PROXY_USER=socksuser +PROXY_PASSWORD=change-me-please +PROXY_PORT=1080 + +# Optional filters. Empty means allow all. +ALLOWED_DEST_FQDN= +ALLOWED_IPS= diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7f2bec0 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.env +*.log +.DS_Store diff --git a/README.hermes.md b/README.hermes.md new file mode 100644 index 0000000..41b9114 --- /dev/null +++ b/README.hermes.md @@ -0,0 +1,49 @@ +# serjs/socks5-server LAN IP deployment + +This folder contains compose examples for running `serjs/go-socks5-proxy`. + +## Important finding on this Mac / OrbStack host + +The Mac is on LAN `192.168.2.0/24` as `192.168.2.69`. +Docker is running inside OrbStack, whose Docker daemon network interface is `198.19.249.2/24`, not the physical `en0` LAN interface. + +Because of that, Docker `macvlan`/`ipvlan` cannot attach directly to macOS `en0` from inside OrbStack. In testing, Compose can create a macvlan container with metadata IP `192.168.2.200`, but the Mac/LAN cannot ARP or connect to it (`192.168.2.200:1080` times out and ARP stays incomplete). So a true same-LAN container IP is normally feasible on a native Linux host with a real NIC, but not directly on this current macOS/OrbStack setup via only docker-compose. + +## Recommended on this Mac: host-published port + +Use `docker-compose.yml`. It runs the SOCKS5 server and publishes port `1080` on the Mac: + +```bash +cp .env.example .env +# edit .env +# then: +docker compose up -d +``` + +Access from LAN: + +```text +192.168.2.69:1080 +``` + +## Real LAN IP version for a Linux host + +Use `docker-compose.macvlan-linux.yml` on a Linux machine physically connected to `192.168.2.0/24`. + +Before using it: + +1. Make sure `192.168.2.200` is outside DHCP range or reserved for this container. +2. Replace `parent: eth0` with the Linux host NIC name. +3. Confirm the intended default gateway. In this chat BOSS asked for `192.168.2.1`, but this Mac's current default gateway is `192.168.2.8`. + +Run: + +```bash +docker compose -f docker-compose.macvlan-linux.yml up -d +``` + +Access: + +```text +192.168.2.200:1080 +``` diff --git a/docker-compose.ipvlan-linux.yml b/docker-compose.ipvlan-linux.yml new file mode 100644 index 0000000..5f7bb7a --- /dev/null +++ b/docker-compose.ipvlan-linux.yml @@ -0,0 +1,26 @@ +# Alternative for native Linux Docker hosts. ipvlan L2 often works better than +# macvlan on switches/APs that dislike multiple MAC addresses behind one port. +# Not expected to work directly on macOS OrbStack for the same VM/NIC reason. + +services: + socks5: + image: serjs/go-socks5-proxy:latest + container_name: socks5-server-lan + restart: unless-stopped + env_file: + - .env + networks: + socks5_lan: + ipv4_address: 192.168.2.200 + +networks: + socks5_lan: + driver: ipvlan + driver_opts: + parent: eth0 + ipvlan_mode: l2 + ipam: + config: + - subnet: 192.168.2.0/24 + gateway: 192.168.2.1 + ip_range: 192.168.2.200/32 diff --git a/docker-compose.macvlan-linux.yml b/docker-compose.macvlan-linux.yml new file mode 100644 index 0000000..39823bb --- /dev/null +++ b/docker-compose.macvlan-linux.yml @@ -0,0 +1,26 @@ +# Use this only on a native Linux Docker host with a real NIC on 192.168.2.0/24. +# It is not expected to work directly on macOS OrbStack because the Docker daemon +# is inside a VM and cannot attach macvlan to macOS en0. + +services: + socks5: + image: serjs/go-socks5-proxy:latest + container_name: socks5-server-lan + restart: unless-stopped + env_file: + - .env + networks: + socks5_lan: + ipv4_address: 192.168.2.200 + +networks: + socks5_lan: + driver: macvlan + driver_opts: + # Replace eth0 with the Linux host's physical NIC, e.g. eno1/enp3s0. + parent: eth0 + ipam: + config: + - subnet: 192.168.2.0/24 + gateway: 192.168.2.1 + ip_range: 192.168.2.200/32 diff --git a/docker-compose.yml b/docker-compose.yml index 1423895..77d05f6 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,9 +1,15 @@ -version: '3' services: - socks5: - restart: always - image: serjs/go-socks5-proxy - env_file: .env + image: serjs/go-socks5-proxy:latest + container_name: socks5-server + restart: unless-stopped + env_file: + - .env ports: - - "1080:1080" + - "0.0.0.0:1080:1080" + healthcheck: + test: ["CMD", "/socks5", "--help"] + interval: 30s + timeout: 5s + retries: 3 + start_period: 10s