docs: add LAN socks5 compose deployment

.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=

.gitignore

@@ -0,0 +1,3 @@
+.env
+*.log
+.DS_Store

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
+```

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

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

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