Bake cross-service port collision avoidance into every service script
With 70+ services sharing a handful of common default ports (emby and jellyfin both default to 8096, changedetection and frigate both default to 5000, arm and nextcloud both default to 8080...), nothing previously checked whether a service's default port was actually free on the host. Whichever service installed second would silently write a compose file claiming an already-held port, only failing at `docker compose up` time. Adds two shared helpers to lib/common.sh: - port_in_use PORT [PROTO] — true if something's already listening - find_free_port VARNAME START [PROTO] — scans upward, writes back the first free port Every service that publishes a fixed host port now scans before writing docker-compose.yml, on every install (not just when adding an explicit additional instance). On a normal single-install host this is a silent no-op; it only changes behavior when something else already holds the port. - The 19 services already given multi-instance support this session had their port scan moved out of the "add instance" branch to run unconditionally, since the same collision risk exists on a plain first install. - 20 more services with previously-hardcoded ports gained scanning for the first time: archivebox, arm, calibre-web, changedetection, drum-rhythm-game, gatus, n8n, nextcloud, onlyoffice, stirling-pdf, uptimekuma, portainer, iopaint (both GPU/CPU compose branches), koha (paired), syncthing (paired), wg-easy (paired, plus WG_PORT env so generated peer configs keep the right Endpoint), homeassistant (bridge-mode only — host mode can only warn), frigate and frigate-audio (multi-port stacks, moved together). - caddy.sh is the deliberate exception: 80/443 stay fixed and only warn on collision, since silently moving Caddy itself would leave nothing listening where any client actually looks. - authelia.sh needs no change — it has no published host port at all. - Every service's standalone bootstrap fallback (sudo bash services/x.sh with no sibling files) got the same two helpers duplicated into its stub block, matching how every other shared helper is already handled there. Documents the full pattern in CLAUDE.md's new "Port collision avoidance" section, including the quoted-heredoc/backtick-escaping gotcha and the network_mode:host limitation (can only scan ports the app takes as a configurable env var). Verified via bash -n on every changed file, plus functional runs seeding occupied ports for each collision shape used here (single, paired, multi-port stacks) and confirming the scan/shift and generated compose/README output are correct — including the emby/jellyfin, nextcloud/arm, and frigate/changedetection collision scenarios that originally motivated this.
This commit is contained in:
Claude
+37
-10
@@ -49,6 +49,21 @@ if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
|
||||
chown -R "$ACTUAL_USER:$ACTUAL_USER" "$@" 2>/dev/null || true
|
||||
}
|
||||
|
||||
port_in_use() {
|
||||
local _port="$1" _proto="${2:-tcp}"
|
||||
local _flag="-tlnH"
|
||||
[ "$_proto" = "udp" ] && _flag="-ulnH"
|
||||
ss "$_flag" "sport = :${_port}" 2>/dev/null | grep -q .
|
||||
}
|
||||
|
||||
find_free_port() {
|
||||
local _varname="$1" _port="$2" _proto="${3:-tcp}"
|
||||
while port_in_use "$_port" "$_proto"; do
|
||||
_port=$((_port + 1))
|
||||
done
|
||||
eval "$_varname='$_port'"
|
||||
}
|
||||
|
||||
# Match common.sh's eval-based pattern so local vars in install_* are set correctly
|
||||
prompt_text() {
|
||||
local _q="$1" _def="$2" _var="$3" _r
|
||||
@@ -198,6 +213,7 @@ install_wg-easy() {
|
||||
require_docker || return 1
|
||||
|
||||
local WGEASY_DIR="$DOCKER_DIR/wg-easy"
|
||||
local WEB_PORT="51821" VPN_PORT="51820"
|
||||
|
||||
if [ "$DRY_RUN" = true ]; then
|
||||
echo "[DRY-RUN] wg-easy would:"
|
||||
@@ -205,14 +221,24 @@ install_wg-easy() {
|
||||
echo " - Auto-detect public IP for WG_HOST"
|
||||
echo " - Generate a random web UI password"
|
||||
echo " - Pin WG_DEFAULT_ADDRESS=10.8.0.x (subnet 10.8.0.0/24)"
|
||||
echo " - Expose port 51821 (web UI) + 51820/udp (VPN)"
|
||||
echo " - Require router port-forward: UDP 51820 → this server"
|
||||
echo " - Expose port 51821 (web UI) + 51820/udp (VPN), both auto-scanned if occupied"
|
||||
echo " - Require router port-forward: UDP <VPN port> → this server"
|
||||
echo " - Offer a Caddy reverse proxy and to start the container"
|
||||
echo " - Offer to also allow SSH from the VPN subnet (additive, doesn't remove public SSH)"
|
||||
echo " - Write sync-ssh-aliases.sh — generates ~/.ssh/config aliases for connected peers"
|
||||
return 0
|
||||
fi
|
||||
|
||||
# Scan for free host ports, moving both together — a plain install
|
||||
# shouldn't silently claim a port another already-running service holds.
|
||||
# Whatever VPN_PORT ends up as is what needs forwarding on the router
|
||||
# (the messaging below reflects the final value, not the 51820 default).
|
||||
# See CLAUDE.md's "Port collision avoidance" section.
|
||||
while port_in_use "$WEB_PORT" || port_in_use "$VPN_PORT" udp; do
|
||||
WEB_PORT=$((WEB_PORT + 1))
|
||||
VPN_PORT=$((VPN_PORT + 1))
|
||||
done
|
||||
|
||||
mkdir -p "$WGEASY_DIR"
|
||||
ensure_docker_dir_ownership "$WGEASY_DIR"
|
||||
cd "$WGEASY_DIR" || return 1
|
||||
@@ -287,11 +313,12 @@ services:
|
||||
- WG_DEFAULT_DNS=1.1.1.1
|
||||
- WG_DEFAULT_ADDRESS=${WG_DEFAULT_ADDRESS}
|
||||
- WG_ALLOWED_IPS=0.0.0.0/0, ::/0
|
||||
- WG_PORT=${VPN_PORT}
|
||||
volumes:
|
||||
- ./config:/etc/wireguard
|
||||
ports:
|
||||
- "51820:51820/udp"
|
||||
- "51821:51821/tcp"
|
||||
- "${VPN_PORT}:${VPN_PORT}/udp"
|
||||
- "${WEB_PORT}:51821/tcp"
|
||||
${_CADDY_NET_BLOCK}${_CADDY_NET_SECTION}
|
||||
WGEASY_COMPOSE
|
||||
|
||||
@@ -416,8 +443,8 @@ SYNCEOF
|
||||
WireGuard VPN with a web UI for managing clients, generating QR codes,
|
||||
and monitoring connections.
|
||||
|
||||
- Web UI: http://localhost:51821
|
||||
- VPN: UDP port 51820 (forward this on your router)
|
||||
- Web UI: http://localhost:${WEB_PORT}
|
||||
- VPN: UDP port ${VPN_PORT} (forward this on your router)
|
||||
- Password: stored in \`.env\` (\`WG_PASSWORD\`)
|
||||
- VPN host: \`$WG_HOST\` (update \`WG_HOST\` in .env if your IP changes)
|
||||
- VPN subnet: \`$WG_SUBNET_CIDR\`
|
||||
@@ -433,10 +460,10 @@ docker compose pull && docker compose up -d # update
|
||||
\`\`\`
|
||||
|
||||
## Router setup
|
||||
Forward **UDP port 51820** to this server's LAN IP for external VPN access.
|
||||
Forward **UDP port ${VPN_PORT}** to this server's LAN IP for external VPN access.
|
||||
|
||||
## Adding clients
|
||||
Open http://localhost:51821, log in with your password, click "+ New Client",
|
||||
Open http://localhost:${WEB_PORT}, log in with your password, click "+ New Client",
|
||||
download or scan the QR code with the WireGuard app.
|
||||
|
||||
## Mesh — peers reach each other automatically
|
||||
@@ -471,11 +498,11 @@ MD
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo " Web UI: http://localhost:51821"
|
||||
echo " Web UI: http://localhost:${WEB_PORT}"
|
||||
echo " Password: $WG_PASSWORD (saved in .env)"
|
||||
[[ -n "$WG_PASSWORD_HASH" ]] && echo " Auth: bcrypt hash configured (v14+ compatible)" \
|
||||
|| echo " Auth: WARNING — bcrypt hash generation failed; see README"
|
||||
echo " Router: forward UDP 51820 → this server for external VPN access"
|
||||
echo " Router: forward UDP ${VPN_PORT} → this server for external VPN access"
|
||||
echo ""
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user