Link each commit in the release changelog to its own commit page

COMMIT_LIST only rendered the bare subject line per commit, with no
way to jump to that specific commit — only the triggering commit
(Source:) had a link. Each line now reads
"- [<short-sha>](<repo>/commit/<sha>) <subject>", matching the same
link style already used for Source.

.env

@@ -1,4 +1,5 @@
-# Socat Proxy Configuration
+PUID=1000 # User id the process runs as
+PGID=1000 # Group id the process runs as
 TARGET_HOST= # Target hostname/IP to proxy to
 TARGET_PORT= # Target port to proxy to
 UNIX_SOCKET_NAME= # Name of the socket file

.gitea/workflows/ci.yml

@@ -0,0 +1,166 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+
+jobs:
+  build-and-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Build Docker image
+        run: docker build -t socat-proxy:ci .
+
+      - name: Smoke test (syntax check)
+        run: docker run --rm --entrypoint sh socat-proxy:ci -n /entrypoint.sh
+
+      - name: Run unit tests
+        run: |
+          docker build --target test -t socat-proxy:test .
+          docker run --rm socat-proxy:test bats /app/tests/entrypoint.bats
+
+      - name: Lint entrypoint.sh with shellcheck
+        run: docker build --target lint -t socat-proxy:lint .
+
+      - name: Scan with Trivy (critical - blocking)
+        run: |
+          docker run --rm \
+            -e DOCKER_HOST=tcp://dockerhost:2375 \
+            --add-host=dockerhost:host-gateway \
+            aquasec/trivy:0.74.0 image --exit-code 1 --severity CRITICAL socat-proxy:ci
+
+      - name: Scan with Trivy (high - informative)
+        run: |
+          docker run --rm \
+            -e DOCKER_HOST=tcp://dockerhost:2375 \
+            --add-host=dockerhost:host-gateway \
+            aquasec/trivy:0.74.0 image --exit-code 0 --severity HIGH socat-proxy:ci
+
+      - name: Publish tagged image
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          BEFORE="${{ github.event.before }}"
+          if [ -n "$BEFORE" ] && [ "$BEFORE" != "0000000000000000000000000000000000000000" ] && git cat-file -e "$BEFORE" 2>/dev/null; then
+            BASE_REF="$BEFORE"
+          else
+            BASE_REF="HEAD~1"
+          fi
+          CHANGED=$(git diff --name-only "$BASE_REF" "${{ github.sha }}")
+          echo "Changed files:"
+          echo "$CHANGED"
+
+          if ! echo "$CHANGED" | grep -qE '^(Dockerfile|entrypoint\.sh|VERSION)$'; then
+            echo "No container-relevant file changed, skipping publish."
+            exit 0
+          fi
+
+          if echo "$CHANGED" | grep -qE '^VERSION$'; then
+            echo "VERSION was manually edited in this push, using it as-is."
+          else
+            echo "VERSION untouched but container files changed, auto-bumping the build number (Z)."
+            OLD_VERSION=$(tr -d '[:space:]' < VERSION)
+            IFS='.' read -r MAJOR MINOR PATCH <<< "$OLD_VERSION"
+            NEW_VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
+            echo "$NEW_VERSION" > VERSION
+
+            git config user.name "socat-proxy-ci"
+            git config user.email "[email protected]"
+            git add VERSION
+            git commit -m "Bump build version to $NEW_VERSION [skip ci]"
+
+            # Belt and suspenders: actions/checkout can leave its own ephemeral
+            # credential injected as an extraheader, which would silently override
+            # the URL-embedded token below. persist-credentials:false on checkout
+            # should already prevent this, but strip it here too just in case.
+            git config --unset-all http.https://git.djeex.fr/.extraheader || true
+
+            git push "https://Djeex:${{ secrets.CI_PUSH_TOKEN }}@git.djeex.fr/Djeex/socat-proxy.git" HEAD:main
+          fi
+
+          VERSION=$(tr -d '[:space:]' < VERSION)
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"
+          MINOR_TAG="${MAJOR}.${MINOR}"
+
+          IMAGE=git.djeex.fr/djeex/socat-proxy
+          echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.djeex.fr -u Djeex --password-stdin
+
+          # Retag the already-built, already-scanned image — never rebuild for publish,
+          # so what ships is byte-for-byte what Trivy just scanned.
+          docker tag socat-proxy:ci "$IMAGE:latest"
+          docker tag socat-proxy:ci "$IMAGE:$MINOR_TAG"
+          docker tag socat-proxy:ci "$IMAGE:$VERSION"
+          docker push "$IMAGE:latest"
+          docker push "$IMAGE:$MINOR_TAG"
+          docker push "$IMAGE:$VERSION"
+
+          TRIGGER_MSG=$(git log -1 --format=%s "${{ github.sha }}")
+          PR_NUM=$(echo "$TRIGGER_MSG" | grep -oE '#[0-9]+' | head -1 | tr -d '#' || true)
+
+          CATEGORY="🔧 Maintenance"
+          CHANGE_TITLE="$TRIGGER_MSG"
+
+          if [ -n "$PR_NUM" ]; then
+            PR_JSON=$(curl -s -H "Authorization: token ${{ secrets.CI_PUSH_TOKEN }}" \
+              "https://git.djeex.fr/api/v1/repos/Djeex/socat-proxy/pulls/$PR_NUM")
+            PR_TITLE=$(echo "$PR_JSON" | jq -r '.title // empty' 2>/dev/null || true)
+            LABELS=$(echo "$PR_JSON" | jq -r '.labels[]?.name' 2>/dev/null || true)
+
+            if [ -n "$PR_TITLE" ]; then
+              CHANGE_TITLE="$PR_TITLE"
+            fi
+
+            if echo "$LABELS" | grep -qx 'bug'; then
+              CATEGORY="⚠️ Hotfix"
+            elif echo "$LABELS" | grep -qx 'major'; then
+              CATEGORY="💥 Breaking change"
+            elif echo "$LABELS" | grep -qx 'minor'; then
+              CATEGORY="✨ Update"
+            fi
+          fi
+
+          REPO_URL="https://git.djeex.fr/Djeex/socat-proxy"
+          COMMIT_LIST=$(git log --no-merges --format="- [%h](${REPO_URL}/commit/%H) %s" "$BASE_REF".."${{ github.sha }}")
+
+          SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
+          SOURCE_LINE="[${SHORT_SHA}](${REPO_URL}/commit/${{ github.sha }})"
+          if [ -n "$PR_NUM" ]; then
+            SOURCE_LINE="[#${PR_NUM}](${REPO_URL}/pulls/${PR_NUM}) · ${SOURCE_LINE}"
+          fi
+
+          BODY=$(cat <<EOF
+          ## Changelog
+          ---
+
+          ### ${CATEGORY}
+          ---
+          ${CHANGE_TITLE}
+
+          **Source:** ${SOURCE_LINE}
+          **Image:** \`${IMAGE}:${VERSION}\`
+
+          **Commits:**
+          ${COMMIT_LIST}
+          EOF
+          )
+
+          JSON_PAYLOAD=$(jq -n \
+            --arg tag "$VERSION" \
+            --arg name "$VERSION" \
+            --arg body "$BODY" \
+            '{tag_name: $tag, name: $name, target_commitish: "main", body: $body}')
+
+          curl -s -o /dev/null -w "Release API response: %{http_code}\n" -X POST \
+            -H "Authorization: token ${{ secrets.CI_PUSH_TOKEN }}" \
+            -H "Content-Type: application/json" \
+            -d "$JSON_PAYLOAD" \
+            "https://git.djeex.fr/api/v1/repos/Djeex/socat-proxy/releases"

Dockerfile

@@ -1,10 +1,26 @@
-FROM alpine:latest
+FROM alpine:3.24.1 AS base
 
-RUN apk add --no-cache socat netcat-openbsd \
+RUN apk add --no-cache socat netcat-openbsd su-exec \
     && rm -rf /var/cache/apk/* /tmp/*
 
 COPY entrypoint.sh VERSION /
 RUN mkdir -p /socket \
     && chmod +x /entrypoint.sh
 
-ENTRYPOINT ["/entrypoint.sh"]
+FROM base AS test
+
+RUN apk add --no-cache bats bash procps
+
+WORKDIR /app
+COPY entrypoint.sh VERSION /app/
+COPY tests/ /app/tests/
+
+FROM base AS lint
+
+RUN apk add --no-cache shellcheck
+RUN shellcheck --severity=error -s sh /entrypoint.sh
+
+# Kept as the last stage so `docker build .` (no --target) still produces
+# the lean prod image, not the `test`/`lint` stages above.
+FROM base
+ENTRYPOINT ["/entrypoint.sh"]

README.MD

@@ -2,17 +2,20 @@
 
 A lightweight Docker container that creates a UNIX socket proxy to TCP connections using socat and Alpine Linux.
 
+> [!NOTE]
+>_Github repo is a mirror of https://git.djeex.fr/Djeex/socat-proxy. You'll find full package, history and release note there._
+
 ## 📑 Table of Contents
 
 - [🚀 Features](#-features)
+- [🔧 How It Works](#-how-it-works)
 - [📋 Use Case](#-use-case)
 - [🛠️ Configuration](#️-configuration)
   - [Environment Variables](#environment-variables)
 - [🚢 Quick Start](#-quick-start)
   - [Using Docker Compose (Recommended)](#using-docker-compose-recommended)
   - [Using Docker Run](#using-docker-run)
-- [🔧 How It Works](#-how-it-works)
-- [💡 Example: Secure Docker Socket Access for Host-Mode Containers](#-example-secure-docker-socket-access-for-host-mode-containers)
+- [💡 Deployment example for Beszel](#-example-secure-docker-socket-access-for-host-mode-containers)
 
 ## 🚀 Features
 
@@ -20,9 +23,22 @@ A lightweight Docker container that creates a UNIX socket proxy to TCP connectio
 - **Socket Management**: Automatic UNIX socket creation and cleanup
 - **Production Ready**: Includes proper error handling and logging
 
+## 🔧 How It Works
+
+1. **Socket Check**: Verifies if UNIX socket exists at startup
+2. **Cleanup**: Removes existing socket file/folder if present
+3. **Socket Creation**: Creates new UNIX socket using `nc -lU`
+4. **Proxy Start**: Starts socat to proxy UNIX socket to TCP endpoint
+
 ## 📋 Use Case
 
-- Proxy Docker socket from a docker proxy to a container in host mode without directly exposing socket to host
+Proxy Docker socket from a docker proxy to a container in host mode without directly exposing socket to host. For example:
+
+[Beszel](https://beszel.dev/) is a monitoring tool that requires `network_mode: host` to function properly. This creates a security challenge: Beszel needs access to the Docker socket, but it cannot reach a containerized docker-socket-proxy due to the network isolation. Running docker-socket-proxy in host mode or exposing port to host would also be highly insecure.
+
+**Socat-proxy solves this problem** by creating a secure bridge between host-mode containers and containerized socket proxies. It exposes a UNIX socket file on the host filesystem that Beszel can access, while securely forwarding all Docker API requests to the socket-proxy running on the bridge network.
+
+![](https://git.djeex.fr/Djeex/socat-proxy/raw/branch/main/illustration/socat-proxy.svg)
 
 ## 🛠️ Configuration
 
@@ -30,6 +46,8 @@ A lightweight Docker container that creates a UNIX socket proxy to TCP connectio
 
 | Variable | Default | Description | Example |
 |----------|---------|-------------|---------|
+| `PUID` | `911` | User ID the process runs as (drops root at startup) | `1000` |
+| `PGID` | `911` | Group ID the process runs as | `1000` |
 | `TARGET_HOST` | - | Target hostname/IP to proxy to | `socket-proxy-beszel` |
 | `TARGET_PORT` | - | Target port to proxy to | `2375` |
 | `UNIX_SOCKET_NAME` | - | Name of the socket file | `docker.sock` |
@@ -43,13 +61,14 @@ A lightweight Docker container that creates a UNIX socket proxy to TCP connectio
 
 1. Create a `.env` file with your configuration:
 ```bash
-# .env
-TARGET_HOST=socket-proxy-beszel
-TARGET_PORT=2375
-UNIX_SOCKET_NAME=docker.sock
-UNIX_SOCKET_PATH=/socket
-HOST_SOCKET_PATH=/docker/beszel-agent/sock
-DEBUG_LEVEL=0
+PUID=1000 #user id the process runs as
+PGID=1000 #group id the process runs as
+TARGET_HOST= #your target host
+TARGET_PORT= #your target host port
+UNIX_SOCKET_NAME= #your socket file name
+UNIX_SOCKET_PATH= #your socket folder path inside socat-proxy
+HOST_SOCKET_PATH= #your socket folder path inside your host
+DEBUG_LEVEL=1
 ```
 
 2. Create a `compose.yml` file:
@@ -58,6 +77,8 @@ services:
   socat-proxy:
     image: git.djeex.fr/djeex/socat-proxy:latest
     environment:
+      - PUID=${PUID}
+      - PGID=${PGID}
       - TARGET_HOST=${TARGET_HOST}
       - TARGET_PORT=${TARGET_PORT}
       - UNIX_SOCKET_NAME=${UNIX_SOCKET_NAME}
@@ -79,28 +100,20 @@ docker compose up -d
 ```bash
 docker run -d \
   --name socat-proxy \
-  -e TARGET_HOST=socket-proxy-beszel \
-  -e TARGET_PORT=2375 \
-  -e UNIX_SOCKET_NAME=docker.sock \
-  -e UNIX_SOCKET_PATH=/socket \
-  -e HOST_SOCKET_PATH=/docker/beszel-agent/sock \
+  -e PUID=1000 #user id the process runs as \
+  -e PGID=1000 #group id the process runs as \
+  -e TARGET_HOST= #your target host \
+  -e TARGET_PORT= #your target host port \
+  -e UNIX_SOCKET_NAME= #your socket file name \
+  -e UNIX_SOCKET_PATH= #your socket folder path inside socat-proxy \
+  -e HOST_SOCKET_PATH= #your socket folder path inside your host\
   -e DEBUG_LEVEL=1 \
-  -v /docker/beszel-agent/sock:/socket \
+  -v ${HOST_SOCKET_PATH}:${UNIX_SOCKET_PATH}$ \
   git.djeex.fr/djeex/socat-proxy:latest
 ```
 
-## 🔧 How It Works
 
-1. **Socket Check**: Verifies if UNIX socket exists at startup
-2. **Cleanup**: Removes existing socket file/folder if present
-3. **Socket Creation**: Creates new UNIX socket using `nc -lU`
-4. **Proxy Start**: Starts socat to proxy UNIX socket to TCP endpoint
-
-## 💡 Example: Secure Docker Socket Access for Host-Mode Containers
-
-[Beszel](https://beszel.dev/) is a monitoring tool that requires `network_mode: host` to function properly. This creates a security challenge: Beszel needs access to the Docker socket, but it cannot reach a containerized docker-socket-proxy due to the network isolation. Running docker-socket-proxy in host mode would be highly insecure.
-
-**Socat-proxy solves this problem** by creating a secure bridge between host-mode containers and containerized socket proxies. It exposes a UNIX socket file on the host filesystem that Beszel can access, while securely forwarding all Docker API requests to the socket-proxy running on the bridge network.
+## 💡 Deployment example for Beszel
 
 ```yaml
 services:
@@ -116,10 +129,12 @@ services:
     volumes:
       - ${HOST_SOCKET_PATH}:${UNIX_SOCKET_PATH}
     restart: unless-stopped
+    depends_on:
+      - ${TARGET_HOST}
 
   socket-proxy:
     image: lscr.io/linuxserver/socket-proxy:latest
-    container_name: socket-proxy-beszel
+    container_name: ${TARGET_HOST}
     security_opt:
       - no-new-privileges:true
     environment:
@@ -140,7 +155,7 @@ services:
     security_opt:
       - no-new-privileges:true
     volumes:
-      - ${HOST_SOCKET_PATH}/docker.sock:/var/run/docker.sock:ro
+      - ${HOST_SOCKET_PATH}/${UNIX_SOCKET_NAME}:/var/run/docker.sock:ro
     environment:
       - #... your Beszel environment var 
     depends_on:

VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

docker-compose.yaml

@@ -3,6 +3,8 @@ services:
   socat-proxy:
     build: .
     environment:
+      - PUID=${PUID}
+      - PGID=${PGID}
       - TARGET_HOST=${TARGET_HOST}
       - TARGET_PORT=${TARGET_PORT}
       - UNIX_SOCKET_NAME=${UNIX_SOCKET_NAME}

entrypoint.sh

@@ -4,121 +4,169 @@ set -e
 CYAN="\033[1;36m"
 NC="\033[0m"
 
-TARGET_HOST=${TARGET_HOST}
-TARGET_PORT=${TARGET_PORT}
-UNIX_SOCKET_NAME=${UNIX_SOCKET_NAME}
-UNIX_SOCKET_PATH=${UNIX_SOCKET_PATH}
-HOST_SOCKET_PATH=${HOST_SOCKET_PATH}
-DEBUG_LEVEL=${DEBUG_LEVEL:-1}  # Default to basic logging
+log()  { echo "$(date '+%Y-%m-%d %H:%M:%S') $*"; }
+fail() { echo "$(date '+%Y-%m-%d %H:%M:%S') [!] $*" >&2; exit 1; }
 
-# Remove trailing slashes to avoid double slashes
+print_banner() {
+    version=$(cat VERSION 2>/dev/null || echo "unknown")
+    title="Socat Proxy - Version ${version}"
+    lines="Source: https://git.djeex.fr/Djeex/socat-proxy
+Mirror: https://github.com/Djeex/socat-proxy"
+
+    width=${#title}
+    old_ifs=$IFS
+    IFS='
+'
+    for l in $lines; do
+        [ ${#l} -gt "$width" ] && width=${#l}
+    done
+    IFS=$old_ifs
+    width=$((width + 2))
+
+    border=""
+    i=0
+    while [ "$i" -lt "$width" ]; do
+        border="${border}─"
+        i=$((i + 1))
+    done
+    printf "${CYAN}╭%s╮${NC}\n" "$border"
+
+    total_pad=$((width - ${#title}))
+    left=$((total_pad / 2))
+    right=$((total_pad - left))
+    printf "${CYAN}│${NC}%*s%s%*s${CYAN}│${NC}\n" "$left" "" "$title" "$right" ""
+
+    printf "${CYAN}├%s┤${NC}\n" "$border"
+
+    IFS='
+'
+    for l in $lines; do
+        printf "${CYAN}│${NC} %-*s${CYAN}│${NC}\n" "$((width - 1))" "$l"
+    done
+    IFS=$old_ifs
+
+    printf "${CYAN}╰%s╯${NC}\n" "$border"
+}
+
+print_banner
+
+DEBUG_LEVEL=${DEBUG_LEVEL:-1}
 UNIX_SOCKET_PATH=${UNIX_SOCKET_PATH%/}
 HOST_SOCKET_PATH=${HOST_SOCKET_PATH%/}
 
 FULL_HOST_SOCKET_PATH="$HOST_SOCKET_PATH/$UNIX_SOCKET_NAME"
 FULL_UNIX_SOCKET_PATH="$UNIX_SOCKET_PATH/$UNIX_SOCKET_NAME"
 
-VERSION=$(cat VERSION)
-
-echo -e "${CYAN}╭────────────────────────────────────────────────╮${NC}"
-echo -e "${CYAN}│${NC}            Socat-proxy - Version ${VERSION}${NC}         ${CYAN}│${NC}"
-echo -e "${CYAN}├────────────────────────────────────────────────┤${NC}"
-echo -e "${CYAN}│${NC} Source: https://git.djeex.fr/Djeex/socat-proxy ${CYAN}│${NC}"
-echo -e "${CYAN}│${NC} Mirror: https://github.com/Djeex/socat-proxy   ${CYAN}│${NC}"
-echo -e "${CYAN}╰────────────────────────────────────────────────╯${NC}"
-
-
 # Validate required environment variables
-if [ -z "$TARGET_HOST" ]; then
-    echo "[✗] TARGET_HOST environment variable is required"
-    exit 1
-fi
+[ -n "$TARGET_HOST" ] || fail "TARGET_HOST environment variable is required"
+[ -n "$TARGET_PORT" ] || fail "TARGET_PORT environment variable is required"
+[ -n "$UNIX_SOCKET_NAME" ] || fail "UNIX_SOCKET_NAME environment variable is required"
+[ -n "$UNIX_SOCKET_PATH" ] || fail "UNIX_SOCKET_PATH environment variable is required"
+[ -n "$HOST_SOCKET_PATH" ] || fail "HOST_SOCKET_PATH environment variable is required"
 
-if [ -z "$TARGET_PORT" ]; then
-    echo "[✗] TARGET_PORT environment variable is required"
-    exit 1
-fi
+PUID=${PUID:-911}
+PGID=${PGID:-911}
 
-if [ -z "$UNIX_SOCKET_NAME" ]; then
-    echo "[✗] UNIX_SOCKET_NAME environment variable is required"
-    exit 1
-fi
+case "$PGID" in
+    ''|*[!0-9]*) fail "PGID '$PGID' is not a valid numeric group id." ;;
+esac
+case "$PUID" in
+    ''|*[!0-9]*) fail "PUID '$PUID' is not a valid numeric user id." ;;
+esac
 
-if [ -z "$UNIX_SOCKET_PATH" ]; then
-    echo "[✗] UNIX_SOCKET_PATH environment variable is required"
-    exit 1
-fi
+log "[i] Requested PUID=$PUID, PGID=$PGID"
 
-if [ -z "$HOST_SOCKET_PATH" ]; then
-    echo "[✗] HOST_SOCKET_PATH environment variable is required"
-    exit 1
+log "[~] Checking group for GID $PGID..."
+GROUP_NAME=$(getent group "$PGID" | cut -d: -f1 || true)
+if [ -z "$GROUP_NAME" ]; then
+    log "[→] No existing group with GID $PGID, creating 'appgroup'."
+    addgroup -g "$PGID" appgroup || fail "Failed to create group with GID $PGID (addgroup exited $?)."
+    GROUP_NAME=appgroup
+else
+    log "[i] Reusing existing group '$GROUP_NAME' (GID $PGID)."
 fi
+log "[✓] Group ready: $GROUP_NAME"
 
-echo "[~] Starting socat proxy..."
-echo "[i] TCP target: $TARGET_HOST:$TARGET_PORT"
-echo "[i] HOST path: $HOST_SOCKET_PATH"
-echo "[i] Full host socket path: $FULL_HOST_SOCKET_PATH"
-echo "[i] Full socket path: $FULL_UNIX_SOCKET_PATH"
+log "[~] Checking user for UID $PUID..."
+USER_NAME=$(getent passwd "$PUID" | cut -d: -f1 || true)
+if [ -z "$USER_NAME" ]; then
+    log "[→] No existing user with UID $PUID, creating 'appuser'."
+    adduser -D -u "$PUID" -G "$GROUP_NAME" appuser || fail "Failed to create user with UID $PUID (adduser exited $?)."
+    USER_NAME=appuser
+else
+    log "[i] Reusing existing user '$USER_NAME' (UID $PUID)."
+fi
+log "[✓] User ready: $USER_NAME"
+
+log "[~] Starting socat proxy..."
+log "[i] TCP target: $TARGET_HOST:$TARGET_PORT"
+log "[i] HOST path: $HOST_SOCKET_PATH"
+log "[i] Full host socket path: $FULL_HOST_SOCKET_PATH"
+log "[i] Full socket path: $FULL_UNIX_SOCKET_PATH"
 
 # Check if socket file/folder exists and handle it
 if [ -e "$FULL_UNIX_SOCKET_PATH" ]; then
-    echo "[~] Socket file/folder $FULL_UNIX_SOCKET_PATH exists, removing it..."
+    log "[~] Socket file/folder $FULL_UNIX_SOCKET_PATH exists, removing it..."
     if rm -rf "$FULL_UNIX_SOCKET_PATH"; then
-        echo "[✓] Removed existing socket $FULL_UNIX_SOCKET_PATH"
+        log "[✓] Removed existing socket $FULL_UNIX_SOCKET_PATH"
     else
-        echo "[✗] Failed to remove existing socket $FULL_UNIX_SOCKET_PATH"
-        exit 1
+        fail "Failed to remove existing socket $FULL_UNIX_SOCKET_PATH"
     fi
 fi
 
-echo "[~] Creating socket directory structure..."
+log "[~] Creating socket directory structure..."
 # Create directory if needed
 if mkdir -p "$UNIX_SOCKET_PATH"; then
-    echo "[✓] Created directory $UNIX_SOCKET_PATH"
+    log "[✓] Created directory $UNIX_SOCKET_PATH"
 else
-    echo "[✗] Failed to create directory $UNIX_SOCKET_PATH"
-    exit 1
+    fail "Failed to create directory $UNIX_SOCKET_PATH"
 fi
 
-echo "[~] Creating socket with netcat..."
+# Grant the target user write access to the socket directory so the
+# su-exec'd socat process below can create the socket file in it.
+log "[~] Setting ownership of $UNIX_SOCKET_PATH to $USER_NAME:$GROUP_NAME..."
+chown "$USER_NAME:$GROUP_NAME" "$UNIX_SOCKET_PATH" || fail "chown on $UNIX_SOCKET_PATH failed — check that the host directory permissions allow it."
+log "[✓] Ownership set on $UNIX_SOCKET_PATH"
+
+log "[~] Preparing socket path..."
 # Create socket file by touching it, then remove it (this creates the path but leaves it clean for socat)
 touch "$FULL_UNIX_SOCKET_PATH"
 rm "$FULL_UNIX_SOCKET_PATH"
-echo "[✓] Socket path prepared at $FULL_UNIX_SOCKET_PATH"
+log "[✓] Socket path prepared at $FULL_UNIX_SOCKET_PATH"
 
 # Debug: Check if socket file exists and its permissions
 if [ -S "$FULL_UNIX_SOCKET_PATH" ]; then
-    echo "[✓] Socket file exists and is a socket"
+    log "[✓] Socket file exists and is a socket"
     ls -la "$FULL_UNIX_SOCKET_PATH"
 else
-    echo "[!] Socket file does not exist or is not a socket"
+    log "[!] Socket file does not exist or is not a socket"
     ls -la "$UNIX_SOCKET_PATH"
 fi
 
-echo "[~] Testing connection to target..."
+log "[~] Testing connection to target..."
 # Test if we can reach the target before starting socat
 if ! nc -z "$TARGET_HOST" "$TARGET_PORT" 2>/dev/null; then
-    echo "[!] Cannot connect to $TARGET_HOST:$TARGET_PORT - socat will retry automatically"
+    log "[!] Cannot connect to $TARGET_HOST:$TARGET_PORT - socat will retry automatically"
 else
-    echo "[✓] Connection to $TARGET_HOST:$TARGET_PORT is working"
+    log "[✓] Connection to $TARGET_HOST:$TARGET_PORT is working"
 fi
 
 # Signal handler for graceful shutdown
 cleanup() {
-    echo "[!] Received SIGTERM, shutting down gracefully..."
-    if [ ! -z "$SOCAT_PID" ]; then
-        echo "[~] Stopping socat process (PID: $SOCAT_PID)..."
+    log "[!] Received SIGTERM, shutting down gracefully..."
+    if [ -n "$SOCAT_PID" ]; then
+        log "[~] Stopping socat process (PID: $SOCAT_PID)..."
         kill "$SOCAT_PID" 2>/dev/null || true
         wait "$SOCAT_PID" 2>/dev/null || true
     fi
-    echo "[~] Cleanup completed, exiting..."
+    log "[~] Cleanup completed, exiting..."
     exit 0
 }
 
 # Set up signal trap
 trap cleanup SIGTERM SIGINT
 
-echo "[~] Starting socat proxy..."
+log "[~] Starting socat proxy..."
 # Start socat with configurable verbosity
 DEBUG_FLAGS=""
 if [ "$DEBUG_LEVEL" -eq 1 ]; then
@@ -129,25 +177,29 @@ elif [ "$DEBUG_LEVEL" -eq 3 ]; then
     DEBUG_FLAGS="-d -d -d"
 fi
 
-echo "[i] Using debug level: $DEBUG_LEVEL ($DEBUG_FLAGS)"
+log "[i] Using debug level: $DEBUG_LEVEL ($DEBUG_FLAGS)"
 
-if socat $DEBUG_FLAGS UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early TCP:$TARGET_HOST:$TARGET_PORT & then
+# mode=666 keeps the socket connectable from another container's UID
+# regardless of PUID/PGID here — see project notes on the socket
+# permission trade-off (this proxy's own threat model is the host/network
+# boundary, not multi-tenant isolation between containers on the same host).
+log "[→] Dropping privileges to $USER_NAME:$GROUP_NAME and starting socat"
+if su-exec "$USER_NAME:$GROUP_NAME" socat $DEBUG_FLAGS UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early,mode=666 TCP:$TARGET_HOST:$TARGET_PORT & then
     SOCAT_PID=$!
-    echo "[✓] Socat started with PID: $SOCAT_PID"
-    echo "[i] Socat command: socat -d -d UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early TCP:$TARGET_HOST:$TARGET_PORT"
-    echo "[~] Container is ready and running..."
-    
+    log "[✓] Socat started with PID: $SOCAT_PID"
+    log "[i] Socat command: socat $DEBUG_FLAGS UNIX-LISTEN:$FULL_UNIX_SOCKET_PATH,fork,unlink-early,mode=666 TCP:$TARGET_HOST:$TARGET_PORT"
+    log "[~] Container is ready and running..."
+
     # Debug: Check socket after socat starts
     sleep 2
     if [ -S "$FULL_UNIX_SOCKET_PATH" ]; then
-        echo "[✓] Socat socket is active"
+        log "[✓] Socat socket is active"
         ls -la "$FULL_UNIX_SOCKET_PATH"
     else
-        echo "[!] Socat socket not found"
+        log "[!] Socat socket not found"
     fi
 else
-    echo "[✗] Failed to start socat proxy"
-    exit 1
+    fail "Failed to start socat proxy"
 fi
 
 # Keep the script alive and wait for socat process
@@ -155,5 +207,4 @@ while kill -0 "$SOCAT_PID" 2>/dev/null; do
     sleep 1
 done
 
-echo "[✗] Socat process has stopped"
-exit 1
+fail "Socat process has stopped"

renovate.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "timezone": "Europe/Paris",
+  "labels": ["bot"],
+  "packageRules": [
+    {
+      "matchManagers": ["dockerfile"],
+      "matchUpdateTypes": ["patch"],
+      "automerge": true
+    },
+    {
+      "matchUpdateTypes": ["major"],
+      "addLabels": ["major"]
+    },
+    {
+      "matchUpdateTypes": ["minor"],
+      "addLabels": ["minor"]
+    }
+  ],
+  "vulnerabilityAlerts": {
+    "enabled": true,
+    "addLabels": ["bug"]
+  }
+}

tests/entrypoint.bats

@@ -0,0 +1,271 @@
+#!/usr/bin/env bats
+#
+# Behavioral tests for entrypoint.sh.
+#
+# Strategy: run the real entrypoint.sh (real socat/nc, no mocks) against a
+# throwaway TCP target and a scratch socket directory, so what's exercised
+# matches production exactly. UNIX-LISTEN binds immediately without the TCP
+# target being reachable, so TARGET_HOST/TARGET_PORT can safely point at
+# nothing for most tests.
+#
+# Process PIDs are looked up on demand via `pgrep -f` against a unique,
+# per-test path/name rather than captured with `$!` — under bats-core's own
+# subshell/job-control plumbing, `$!` does not reliably resolve to the
+# process actually started here.
+
+setup() {
+    TEST_DIR="$(mktemp -d)"
+    # mktemp defaults to 700 (root-only traversal); a real bind-mounted host
+    # directory is typically world-traversable, so match that here — otherwise
+    # the non-root user entrypoint.sh drops to can't even reach its own
+    # (correctly chowned) socket subdirectory.
+    chmod 755 "$TEST_DIR"
+    cp "$BATS_TEST_DIRNAME/../entrypoint.sh" "$TEST_DIR/"
+    cp "$BATS_TEST_DIRNAME/../VERSION" "$TEST_DIR/"
+    chmod +x "$TEST_DIR/entrypoint.sh"
+
+    export TARGET_HOST=127.0.0.1
+    export TARGET_PORT=1
+    export UNIX_SOCKET_NAME="test-$BATS_TEST_NUMBER.sock"
+    export UNIX_SOCKET_PATH="$TEST_DIR/socket"
+    export HOST_SOCKET_PATH="$TEST_DIR/host"
+    unset DEBUG_LEVEL
+}
+
+teardown() {
+    pkill -9 -f "$TEST_DIR/entrypoint.sh" 2>/dev/null
+    pkill -9 -f "UNIX-LISTEN:.*$UNIX_SOCKET_NAME" 2>/dev/null
+    pkill -9 -f "nc .*34599" 2>/dev/null
+    rm -rf "$TEST_DIR"
+}
+
+run_entrypoint_bg() {
+    LOG="$TEST_DIR/out.log"
+    # Invoked via the absolute path (not a bare `./entrypoint.sh`) so its
+    # /proc cmdline actually contains $TEST_DIR for entrypoint_pid() to match.
+    ( cd "$TEST_DIR" && exec "$TEST_DIR/entrypoint.sh" >"$LOG" 2>&1 ) &
+    disown 2>/dev/null || true
+}
+
+entrypoint_pid() {
+    pgrep -f "$TEST_DIR/entrypoint.sh" | head -n1
+}
+
+socat_pid() {
+    pgrep -f "UNIX-LISTEN:.*$UNIX_SOCKET_NAME" | head -n1
+}
+
+wait_for_log() {
+    pattern="$1"
+    tries=0
+    while [ "$tries" -lt 20 ]; do
+        grep -qE "$pattern" "$LOG" 2>/dev/null && return 0
+        tries=$((tries + 1))
+        sleep 0.25
+    done
+    return 1
+}
+
+wait_for_pid_gone() {
+    pid="$1"
+    tries=0
+    while kill -0 "$pid" 2>/dev/null && [ "$tries" -lt 20 ]; do
+        tries=$((tries + 1))
+        sleep 0.25
+    done
+    ! kill -0 "$pid" 2>/dev/null
+}
+
+# ---- Environment variable validation -------------------------------------
+
+@test "fails when TARGET_HOST is missing" {
+    unset TARGET_HOST
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"TARGET_HOST environment variable is required"* ]]
+}
+
+@test "fails when TARGET_PORT is missing" {
+    unset TARGET_PORT
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"TARGET_PORT environment variable is required"* ]]
+}
+
+@test "fails when UNIX_SOCKET_NAME is missing" {
+    unset UNIX_SOCKET_NAME
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"UNIX_SOCKET_NAME environment variable is required"* ]]
+}
+
+@test "fails when UNIX_SOCKET_PATH is missing" {
+    unset UNIX_SOCKET_PATH
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"UNIX_SOCKET_PATH environment variable is required"* ]]
+}
+
+@test "fails when HOST_SOCKET_PATH is missing" {
+    unset HOST_SOCKET_PATH
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"HOST_SOCKET_PATH environment variable is required"* ]]
+}
+
+# ---- PUID/PGID privilege dropping ------------------------------------------
+
+@test "fails when PUID is not numeric" {
+    export PUID=abc
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"PUID 'abc' is not a valid numeric user id."* ]]
+}
+
+@test "fails when PGID is not numeric" {
+    export PGID=abc
+    run "$TEST_DIR/entrypoint.sh"
+    [ "$status" -eq 1 ]
+    [[ "$output" == *"PGID 'abc' is not a valid numeric group id."* ]]
+}
+
+@test "creates appuser/appgroup at the default 911 PUID/PGID and owns the socket dir" {
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "No existing group with GID 911, creating 'appgroup'" "$LOG"
+    grep -q "No existing user with UID 911, creating 'appuser'" "$LOG"
+    owner="$(stat -c '%U:%G' "$UNIX_SOCKET_PATH")"
+    [ "$owner" = "appuser:appgroup" ]
+}
+
+@test "reuses an existing user/group instead of creating one" {
+    export PUID=0
+    export PGID=0
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "Reusing existing group 'root' (GID 0)" "$LOG"
+    grep -q "Reusing existing user 'root' (UID 0)" "$LOG"
+}
+
+@test "creates the socket with mode 666 so other-UID consumers can connect" {
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    mode="$(stat -c '%a' "$UNIX_SOCKET_PATH/$UNIX_SOCKET_NAME")"
+    [ "$mode" = "666" ]
+}
+
+@test "prints the version banner from the VERSION file" {
+    echo "9.9.9" > "$TEST_DIR/VERSION"
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "Version 9.9.9" "$LOG"
+}
+
+# ---- Socket path preparation ----------------------------------------------
+
+@test "removes a pre-existing file at the socket path before starting" {
+    mkdir -p "$UNIX_SOCKET_PATH"
+    touch "$UNIX_SOCKET_PATH/$UNIX_SOCKET_NAME"
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "exists, removing it" "$LOG"
+    grep -q "Removed existing socket" "$LOG"
+}
+
+@test "creates the socket directory when it does not exist" {
+    [ ! -d "$UNIX_SOCKET_PATH" ]
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "Created directory $UNIX_SOCKET_PATH" "$LOG"
+    [ -d "$UNIX_SOCKET_PATH" ]
+}
+
+@test "reports the socat-created socket as active once it is listening" {
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "Socat socket is active" "$LOG"
+    [ -S "$UNIX_SOCKET_PATH/$UNIX_SOCKET_NAME" ]
+}
+
+# ---- Target connectivity check (informational, non-fatal) -----------------
+
+@test "warns but continues when the TCP target is unreachable" {
+    export TARGET_PORT=1
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "Cannot connect to $TARGET_HOST:$TARGET_PORT" "$LOG"
+    grep -q "Container is ready and running" "$LOG"
+}
+
+@test "reports success when the TCP target is reachable" {
+    ( nc -l 127.0.0.1 34599 >/dev/null 2>&1 & )
+    disown 2>/dev/null || true
+    sleep 0.3
+    export TARGET_PORT=34599
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+    grep -q "Connection to $TARGET_HOST:$TARGET_PORT is working" "$LOG"
+}
+
+# ---- Debug level -> socat flags mapping -----------------------------------
+
+@test "maps an unset DEBUG_LEVEL default of 1 to a single -d flag" {
+    run_entrypoint_bg
+    wait_for_log "Using debug level"
+    grep -q "Using debug level: 1 (-d)" "$LOG"
+}
+
+@test "maps DEBUG_LEVEL=2 to two -d flags" {
+    export DEBUG_LEVEL=2
+    run_entrypoint_bg
+    wait_for_log "Using debug level"
+    grep -q "Using debug level: 2 (-d -d)" "$LOG"
+}
+
+@test "maps DEBUG_LEVEL=3 to three -d flags" {
+    export DEBUG_LEVEL=3
+    run_entrypoint_bg
+    wait_for_log "Using debug level"
+    grep -q "Using debug level: 3 (-d -d -d)" "$LOG"
+}
+
+@test "maps an unrecognized DEBUG_LEVEL to no debug flags" {
+    export DEBUG_LEVEL=0
+    run_entrypoint_bg
+    wait_for_log "Using debug level"
+    grep -q "Using debug level: 0 ()" "$LOG"
+}
+
+# ---- Shutdown behavior ------------------------------------------------------
+
+@test "shuts down gracefully and stops socat on SIGTERM" {
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+
+    ep_pid="$(entrypoint_pid)"
+    sc_pid="$(socat_pid)"
+    [ -n "$ep_pid" ]
+    [ -n "$sc_pid" ]
+
+    kill -TERM "$ep_pid"
+    wait_for_pid_gone "$ep_pid"
+
+    grep -q "Received SIGTERM, shutting down gracefully" "$LOG"
+    grep -q "Cleanup completed, exiting" "$LOG"
+    ! kill -0 "$sc_pid" 2>/dev/null
+}
+
+@test "exits 1 once socat's process dies unexpectedly" {
+    run_entrypoint_bg
+    wait_for_log "Socat socket is active|Socat socket not found"
+
+    ep_pid="$(entrypoint_pid)"
+    sc_pid="$(socat_pid)"
+    [ -n "$ep_pid" ]
+    [ -n "$sc_pid" ]
+
+    kill -9 "$sc_pid"
+    wait_for_pid_gone "$ep_pid"
+
+    grep -q "Socat process has stopped" "$LOG"
+}