root/ubuntu-post-install
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Bake cross-service port collision avoidance into every service script

Browse Source 
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
2026-08-09 23:55:49 +00:00
parent b860a8b174
commit 9e06ed4b83
42 changed files with 1269 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files
services/koha.sh
+41 -15
View File
@@ -45,6 +45,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'"
}
generate_password() {
local _len="${1:-32}"
tr -dc 'A-Za-z0-9' < /dev/urandom | head -c "$_len"
@@ -196,6 +211,17 @@ install_koha() {
require_docker || return 1
local KOHA_DIR="$DOCKER_DIR/koha"
local OPAC_PORT="8097" STAFF_PORT="8098"
# Scan for free host ports, moving both together — a plain install
# shouldn't silently claim a port another already-running service holds.
# Run before any prompts so every message below (including DRY-RUN)
# reflects the real port. See CLAUDE.md's "Port collision avoidance"
# section.
while port_in_use "$OPAC_PORT" || port_in_use "$STAFF_PORT"; do
OPAC_PORT=$((OPAC_PORT + 1))
STAFF_PORT=$((STAFF_PORT + 1))
done
echo ""
echo "╔═══════════════════════════════════════════════════════════════════╗"
@@ -211,7 +237,7 @@ install_koha() {
echo " SETUP OVERVIEW:"
echo " 1) Answer the questions below (collects library details + credentials)"
echo " 2) Koha starts — takes 2–3 min on first boot"
echo " 3) Open http://localhost:8098 and complete the brief web installer (~2 min)"
echo " 3) Open http://localhost:${STAFF_PORT} and complete the brief web installer (~2 min)"
echo " 4) Run $KOHA_DIR/post-setup.sh to auto-configure library, items, locations"
echo ""
@@ -219,8 +245,8 @@ install_koha() {
echo "[DRY-RUN] Would create $KOHA_DIR with docker-compose.yml + config-main.env"
echo "[DRY-RUN] Would deploy teogramm/koha + MariaDB (./data/) + Memcached + RabbitMQ"
echo "[DRY-RUN] Would generate post-setup.sh for REST API configuration"
echo "[DRY-RUN] OPAC (patron UI): port 8097"
echo "[DRY-RUN] Staff/admin: port 8098"
echo "[DRY-RUN] OPAC (patron UI): port $OPAC_PORT"
echo "[DRY-RUN] Staff/admin: port $STAFF_PORT"
return 0
fi
@@ -399,8 +425,8 @@ services:
env_file:
- config-main.env
ports:
- "8097:8080"
- "8098:8081"
- "${OPAC_PORT}:8080"
- "${STAFF_PORT}:8081"
depends_on:
- koha-db
- koha-memcached
@@ -485,13 +511,13 @@ KOHA_ENV
cat > post-setup.sh << POSTSETUP
#!/bin/bash
# post-setup.sh — Run AFTER completing the Koha web installer at http://localhost:8098
# post-setup.sh — Run AFTER completing the Koha web installer at http://localhost:${STAFF_PORT}
# Configures library, item types, and shelf locations via the Koha REST API.
# Generated by ubuntu-post-install on $(date '+%F').
set -uo pipefail
KOHA_STAFF_URL="http://localhost:8098"
KOHA_STAFF_URL="http://localhost:${STAFF_PORT}"
KOHA_DIR="${KOHA_DIR}"
CONF="\${KOHA_DIR}/config-main.env"
@@ -627,8 +653,8 @@ echo "════════════════════════
echo ""
echo " Your Koha library is ready to use."
echo ""
echo " OPAC (patron browsing): http://localhost:8097"
echo " Staff / admin: http://localhost:8098"
echo " OPAC (patron browsing): http://localhost:${OPAC_PORT}"
echo " Staff / admin: http://localhost:${STAFF_PORT}"
echo ""
echo " Next steps in Staff UI:"
echo " 1. Administration → Patron categories → add patron types"
@@ -658,8 +684,8 @@ POSTSETUP
Full Integrated Library System for managing a physical book collection.
## Access
- **OPAC** (patron browsing): http://localhost:8097
- **Staff / admin**: http://localhost:8098
- **OPAC** (patron browsing): http://localhost:${OPAC_PORT}
- **Staff / admin**: http://localhost:${STAFF_PORT}
## Quick setup (4 steps)
@@ -671,7 +697,7 @@ docker compose up -d
Takes 2–3 minutes on first boot while Koha initialises.
### Step 2 — Complete the web installer
1. Open **http://localhost:8098**
1. Open **http://localhost:${STAFF_PORT}**
2. You may see a "Database connection" page first — wait 1–2 min and refresh
3. The installer wizard appears automatically:
- **Language**: click "Install for language English" → Continue
@@ -743,12 +769,12 @@ MD
echo " └──────────────────────────────────────────────────────────────┘"
echo ""
echo " NEXT STEPS:"
echo " 1. Wait ~3 min, then open: http://localhost:8098"
echo " 1. Wait ~3 min, then open: http://localhost:${STAFF_PORT}"
echo " 2. Complete the web installer (use password above when asked)"
echo " 3. Run: sudo $KOHA_DIR/post-setup.sh"
echo ""
echo " OPAC (patron UI): http://localhost:8097"
echo " Staff / admin: http://localhost:8098"
echo " OPAC (patron UI): http://localhost:${OPAC_PORT}"
echo " Staff / admin: http://localhost:${STAFF_PORT}"
echo ""
}