From cb8b2986487df0c50c8b8e8abe6c1ead433ad483 Mon Sep 17 00:00:00 2001
From: lingfish <jason@lucid.net.au>
Date: Fri, 27 Feb 2026 11:24:45 +1100
Subject: [PATCH] Final changes. This modifies the `dev-docs` script a little
 to either use `docker-compose` or `podman-compose`. I've found that Podman
 runs smoother this way, and it isn't required to install `docker-compose`.

---
 docs/.env                           |  2 +-
 docs/Dockerfile                     |  2 +-
 docs/docker-compose.yaml            |  6 ++++--
 docs/how-to/develop-on-borgmatic.md | 25 +++++++++++++++++++++++--
 scripts/dev-docs                    | 16 ++++++++++------
 5 files changed, 39 insertions(+), 12 deletions(-)

diff --git a/docs/.env b/docs/.env
index c0c68b1c..c88bfa87 100644
--- a/docs/.env
+++ b/docs/.env
@@ -1 +1 @@
-PORT=3000
\ No newline at end of file
+PORT=8080
\ No newline at end of file
diff --git a/docs/Dockerfile b/docs/Dockerfile
index c57e03e7..315d4222 100644
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@@ -12,7 +12,7 @@ RUN /app/docs/fetch-contributors >> /contributors.html
 FROM docker.io/node:22.4.0-alpine AS html
 
 ARG ENVIRONMENT=production
-ARG PORT=3000
+ARG PORT=${PORT}
 
 WORKDIR /source
 
diff --git a/docs/docker-compose.yaml b/docs/docker-compose.yaml
index 6e72b481..d2e8d685 100644
--- a/docs/docker-compose.yaml
+++ b/docs/docker-compose.yaml
@@ -3,7 +3,7 @@ services:
     image: public.ecr.aws/docker/library/traefik:3.5.3
     container_name: borgmatic-docs-traefik
     environment:
-      - PORT=${PORT}
+      - PORT=${PORT:-8080}
     command:
       - "--global.checkNewVersion=false"
       - "--global.sendAnonymousUsage=false"
@@ -39,7 +39,9 @@ services:
       context: ..
       args:
         ENVIRONMENT: development
-        PORT: 3000
+        PORT: ${PORT:-8080}
+    environment:
+      - PORT=${PORT:-8080}
   message:
     image: alpine
     container_name: borgmatic-docs-message
diff --git a/docs/how-to/develop-on-borgmatic.md b/docs/how-to/develop-on-borgmatic.md
index 762abc36..7c0b9077 100644
--- a/docs/how-to/develop-on-borgmatic.md
+++ b/docs/how-to/develop-on-borgmatic.md
@@ -190,8 +190,28 @@ This requires Docker (or Podman; see below) to be installed on your system.
 This script assumes you have permission to run `docker`. If you don't, then
 you may need to run with `sudo`.
 
+### How to choose a different port
+
+You can choose a different listening port in two ways:
+
+#### 1. Modify the `.env` file
+
+1.  Open `docs/.env`.
+2.  Change `PORT=8080` to your desired port number (e.g., `PORT=3000`).
+3.  Run the development script: `scripts/dev-docs`.
+
+#### 2. Use an environment variable
+
+Alternatively, you can override the port directly from your terminal without
+modifying any files:
+
+```bash
+PORT=3000 ./scripts/dev-docs
+```
+
 After you run the script, you can point your web browser at
-http://localhost:8080/borgmatic/ to view the documentation with your changes.
+http://localhost:8080/borgmatic/ (or your chosen port) to view the documentation
+with your changes.
 
 To close the documentation server, ctrl-C the script. Note that it does not
 currently auto-reload, so you'll need to stop it and re-run it for any
@@ -206,7 +226,8 @@ borgmatic's developer build for documentation optionally supports using
 
 Setting up Podman is outside the scope of this documentation. But once you
 install and configure Podman, then `scripts/dev-docs` should automatically use
-Podman instead of Docker.
+Podman instead of Docker (make sure you have
+[`podman-compose`](https://github.com/containers/podman-compose) installed).
 
 
 ## Use of generative AI
diff --git a/scripts/dev-docs b/scripts/dev-docs
index f1ac6139..590fb56c 100755
--- a/scripts/dev-docs
+++ b/scripts/dev-docs
@@ -2,11 +2,15 @@
 
 set -e
 
-USER_PODMAN_SOCKET_PATH=/run/user/$UID/podman/podman.sock
-
-if [ -e "$USER_PODMAN_SOCKET_PATH" ]; then
-    export DOCKER_HOST="unix://$USER_PODMAN_SOCKET_PATH"
-    export CONTAINER_SOCKET_PATH="$USER_PODMAN_SOCKET_PATH"
+if command -v podman >/dev/null 2>&1; then
+    if ! command -v podman-compose >/dev/null 2>&1; then
+        echo "Error: podman is installed, but podman-compose is missing." >&2
+        exit 1
+    fi
+    COMPOSE_CMD="podman-compose"
+    export CONTAINER_SOCKET_PATH="${XDG_RUNTIME_DIR:-/run/user/$UID}/podman/podman.sock"
+else
+    COMPOSE_CMD="docker-compose"
 fi
 
-BUILDKIT_PROGRESS=plain docker-compose --file docs/docker-compose.yaml up --build --force-recreate
+BUILDKIT_PROGRESS=plain $COMPOSE_CMD --file docs/docker-compose.yaml up --build --force-recreate