proxy/README.md

# Nginx + Certbot + ACME‑DNS Proxy Stack

*[Full documentation → docs site](https://youruser.github.io/proxy-stack/)*

Simple reverse‑proxy setup packaged in a single Docker image.  Nginx handles HTTP/S and TCP/UDP streams; Certbot issues and renews Let’s Encrypt certificates via ACME‑DNS (DNS‑01). packaged in a single Docker image.  Nginx handles HTTP/S and TCP/UDP streams; Certbot issues and renews Let’s Encrypt certificates via ACME‑DNS (DNS‑01).

---

## What’s in this repo

| Path / file         | Purpose                                              |
| ------------------- | ---------------------------------------------------- |
| `dockerfile.debian` | Builds the image (Debian slim + Nginx + Certbot)     |
| `compose.yml`       | One‑service Docker Compose file                      |
| `acme-dns-auth.py`  | Helper script called by Certbot for DNS‑01           |
| `certbot-runner`    | Convenience wrapper to open a shell in the image     |
| `conf.d/`           | **Not tracked** – drop HTTP/S vhost configs here     |
| `stream.d/`         | **Not tracked** – drop stream (TCP/UDP) configs here |
| `letsencrypt/`      | Empty volume for keys/certs (git‑ignored)            |
| `work/`             | Certbot cache (git‑ignored)                          |

---

## Prerequisites

* Docker 24 or later
* Docker Compose v2 (or Docker Swarm if you prefer)

---

## Quick start (single node)

```bash
# clone
$ git clone https://github.com/youruser/proxy-stack.git
$ cd proxy-stack

# create runtime dirs so volume binds don’t fail
$ mkdir -p letsencrypt work

# build the image (or pull one you published)
$ docker build -t proxy:latest -f dockerfile.debian .

# start Nginx + Certbot
$ IMAGE_NAME=proxy:latest docker compose up -d

# obtain an initial certificate (DNS‑01)
$ DOMAIN=example.com ./certbot-runner
# follow the prompts → add the TXT/CNAME → press <enter>
```

When certificates renew, Certbot reloads Nginx automatically.

---

## Certificates (DNS‑01 quick guide)

```bash
# Run inside the container (root)
certbot certonly \
  --manual \
  --manual-auth-hook /etc/letsencrypt/acme-dns-auth.py \
  --preferred-challenges dns \
  --debug-challenges \
  -d '*.your-domain' -d your-domain
```

1. The hook registers (or re‑uses) an **acme‑dns** account and prints a CNAME like:

```text
_acme-challenge.your-domain.  CNAME  8a1b12c3-...acme-dns.io.
```

2. Create that CNAME in *your* authoritative DNS zone (or update if it exists).
3. Press **<Enter>** – Certbot validates, stores the certs under
`/etc/letsencrypt/live/your-domain/`, and reloads Nginx.

That’s it – future renewals happen automatically (`certbot renew`).

---

## Directory rules

Everything that contains private keys or runtime state is ignored by Git:

```text
letsencrypt/     # keys, certs, renewal configs
work/            # Certbot cache
conf.d/          # your real vhosts – ignored
stream.d/        # your real stream configs – ignored
```

Provide examples by naming them `*.example.conf`; those are the only files tracked inside `conf.d/` and `stream.d/`.

---

## Updating

```bash
# Rebuild image when Nginx or Certbot update
$ docker build -t proxy:latest . && docker compose up -d
```

---

## License

Released under **GPL‑2.0** – see `LICENSE` for full text.