118 lines
4.9 KiB
Markdown
118 lines
4.9 KiB
Markdown
# 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.
|
||
|