initial public commit

2025-06-18 17:16:13 +00:00 · 2025-06-18 17:16:13 +00:00 · 6bd9323fed
commit 6bd9323fed
9 changed files with 645 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,118 @@
+# Nginx + Certbot + ACME‑DNS Proxy Stack
+
+> **A batteries‑included reverse‑proxy scaffold that Just Works™ on a single node or a Docker Swarm.**
+>
+> *Old‑school Unix philosophy under the hood, modern container workflow on top.*
+
+---
+
+## ✨ What you get
+
+| Component                    | Job                                                                         |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| **Nginx**                    | Serves HTTP/S, terminates TLS, proxies upstreams, handles TCP/UDP streams   |
+| **Certbot**                  | Automates Let’s Encrypt certificate issuance / renewal                      |
+| **acme‑dns‑auth.py**         | ACME‑DNS helper for DNS‑01 challenges (wildcards, no public port 80 needed) |
+| **Docker (image & compose)** | Reproducible environment; optional Swarm placement rules                    |
+
+---
+
+## 🗺️ Repo layout
+
+```
+.
+├── acme-dns-auth.py      # DNS‑01 hook script (public upstream helper)
+├── certbot-runner        # Convenience wrapper for interactive work inside the image
+├── new-domain-runner     # Example one‑shot script for ad‑hoc certs
+├── compose.yml           # Single‑service stack definition
+├── dockerfile.debian     # Image build (Debian slim + Nginx + Certbot)
+├── conf.d/               # Per‑vhost HTTP configs
+├── stream.d/             # TCP/UDP proxy configs (PostgreSQL, MQTT, …)
+├── letsencrypt/          # **Empty dir – private keys & certs live here at runtime**
+├── work/                 # Certbot working directory (also ignored by Git)
+└── lib/backups/          # Optional local backup dumps (ignored by Git)
+```
+
+---
+
+## 🚀 Quick start
+
+> **Prerequisites**: Docker (24 +) & Docker Compose v2, or Docker Swarm if you want clustering.
+
+```bash
+# 1. Clone
+$ git clone https://github.com/youruser/proxy-stack.git
+$ cd proxy-stack
+
+# 2. Create empty state dirs so the volume binds succeed
+$ mkdir -p letsencrypt work lib/backups
+$ touch letsencrypt/.gitkeep work/.gitkeep lib/backups/.gitkeep
+
+# 3. (Optional) Build your own image
+$ docker build -t my-proxy:latest -f dockerfile.debian .
+
+# 4. Launch the stack (Compose)
+$ IMAGE_NAME=my-proxy:latest docker compose up -d
+
+# 5. Obtain the first certificate (DNS‑01)
+$ DOMAIN=my.example.com ./new-domain-runner
+# Follow the prompts → add the TXT record → hit <Enter>
+```
+
+### Swarm mode
+
+```bash
+# Initialize swarm once per host (if not already a manager)
+$ docker swarm init
+
+# Deploy with placement label (edit compose.yml if needed)
+$ docker stack deploy -c compose.yml proxy
+```
+
+---
+
+## 🔐 TLS & certificates
+
+* **Automatic renewals** – A cron inside the container runs `certbot renew` and hot‑reloads Nginx.
+* **No secrets in Git** – `letsencrypt/` is `gitignored`; keys stay on disk only.
+* **acme‑dns** – Ideal when ports 80/443 are busy or you need wildcard certs. Change `ACMEDNS_URL` via env var if you self‑host acme‑dns.
+
+---
+
+## ⚙️ Configuration knobs
+
+| Variable        | Default                         | Purpose                                                  |
+| --------------- | ------------------------------- | -------------------------------------------------------- |
+| `IMAGE_NAME`    | `ghcr.io/youruser/proxy:latest` | Override in scripts / compose to point at your own build |
+| `ACMEDNS_URL`   | `https://auth.acme-dns.io`      | Where `acme-dns-auth.py` registers & updates records     |
+| `CERTBOT_EMAIL` | –                               | Address Certbot uses for expiry mails                    |
+| Swarm label     | `node.labels.server_id==lnd1`   | Example placement constraint – comment or change         |
+
+Edit `conf.d/*.conf` and `stream.d/*.conf` to define your virtual hosts and upstreams.
+
+---
+
+## 🛠️ Maintenance
+
+| Task                                     | Old‑school command                       | Modern alternative                            |
+| ---------------------------------------- | ---------------------------------------- | --------------------------------------------- |
+| Rebuild image after Nginx or OpenSSL CVE | `docker build -t my-proxy .`             | GitHub Actions → `docker buildx build --push` |
+| List certs expiring in ≤30 days          | `docker exec proxy certbot certificates` | Prometheus + exporter                         |
+| Tail logs                                | `docker compose logs -f proxy`           | Grafana Loki                                  |
+
+---
+
+## 🤝 Contributing
+
+Patches and issues are welcome – just follow the **kernel‑style rule**: *one patch, one purpose.*
+
+1. Fork → branch → commit (signed‑off)
+2. Make sure `pre-commit run --all` passes (gitleaks, shellcheck, etc.)
+3. Open a PR.
+
+---
+
+## 📜 License
+
+This project is released under the **GNU General Public License v2.0** – see [`LICENSE`](LICENSE) for details.
+