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

@@ -1 +1 @@
-PORT=3000
+PORT=8080

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
 

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

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

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