docker-compose docs

Author: ZhuchkaTriplesix

README.md

@@ -36,6 +36,8 @@ cp .env.example .env
 docker compose -f docker-compose.prod.yml --env-file .env up -d --build
 ```
 
+If Compose fails because port 80 (or 443) is already in use, see **Production** / troubleshooting in [`docs-site/README.md`](docs-site/README.md).
+
 ## Installation
 
 ```bash

docs-site/.env.example

@@ -1,2 +1,7 @@
 OXYJWT_DOCS_DOMAIN=oxyjwt.queryahub.com
 ACME_EMAIL=admin@queryahub.com
+
+# Only used by docker-compose.prod.yml for Caddy’s published ports on the host.
+# Defaults 80/443. Change if those ports are already in use (see docs-site/README.md).
+# CADDY_HTTP_PORT=80
+# CADDY_HTTPS_PORT=443

docs-site/README.md

@@ -55,5 +55,20 @@ The site will be available at `https://oxyjwt.queryahub.com`.
 Server requirements:
 
 - DNS for `oxyjwt.queryahub.com` points to this server.
-- Ports `80` and `443` are open.
-- No other service is already using ports `80` or `443`.
+- Ports `80` and `443` are open to the public internet (or HTTP-01 certificate issuance can fail).
+- **Nothing else** should bind the **same** host ports that Caddy uses for this stack.
+
+### “Bind for 0.0.0.0:80 failed: port is already allocated”
+
+Port `80` (or `443`) on the machine is already used — often by another reverse proxy, OpenLiteSpeed, or a second Docker Compose project.
+
+1. **Preferred if you already have a reverse proxy on 80/443**  
+   Do not publish Caddy on the host. Run only the static site, or add an upstream in your **existing** proxy for `Host: oxyjwt.queryahub.com` to the Nginx in the `docs` service. Example: expose the docs container on `127.0.0.1:9080` and configure your main proxy to `proxy_pass` there with TLS. This stack is then a single `docs` service without the bundled `caddy` service, or Caddy is internal-only (no `ports:` on `caddy`).
+
+2. **If this server should be the only listener on 80/443**  
+   Stop or rebind the other service (for example, move it behind the same Caddy) so **this** Caddy can bind `80:80` and `443:443`.
+
+3. **Temporary / non-standard host ports (not for public HTTPS on default ports)**  
+   In `.env` you can set host ports, for example:
+   `CADDY_HTTP_PORT=18080` and `CADDY_HTTPS_PORT=18443`.  
+   Let’s Encrypt **HTTP-01** validation still expects port **80** on your **public** IP. If the world still hits another process on 80, certificates will not issue correctly unless you use a DNS challenge (not configured in the bundled `Caddyfile`) or terminate TLS in front of this Caddy.

docs-site/docker-compose.prod.yml

@@ -15,9 +15,12 @@ services:
     environment:
       ACME_EMAIL: "${ACME_EMAIL:-admin@queryahub.com}"
       OXYJWT_DOCS_DOMAIN: "${OXYJWT_DOCS_DOMAIN:-oxyjwt.queryahub.com}"
+    # Host ports must be free. If 80/443 are taken by another reverse proxy, do not
+    # publish Caddy on the host: put `oxyjwt.queryahub.com` in that proxy and only
+    # expose the `docs` service (or run Caddy on other host ports and read README).
     ports:
-      - "80:80"
-      - "443:443"
+      - "${CADDY_HTTP_PORT:-80}:80"
+      - "${CADDY_HTTPS_PORT:-443}:443"
     restart: unless-stopped
     volumes:
       - ./Caddyfile:/etc/caddy/Caddyfile:ro