# Spec: Central Nginx reverse proxy MVP

## Metadata
- Type: Spec
- Status: Draft / approval required before infrastructure mutation
- Project: Homelab Operations
- Created: 2026-06-07
- Updated: 2026-06-07

## Objective

Deploy a standard LAN/Tailscale-only Nginx reverse proxy for homelab web services and validate it by proxying one low-risk service with HTTPS.

## Background

Current state:

- Services use direct IP/ports or per-host Nginx/bootstrap TLS.
- No central reverse proxy/TLS standard exists.
- Internal DNS is imperfect: public wildcard records point externally and local overrides are ad hoc.
- User selected dedicated DNS service as the target internal DNS direction.
- User asked whether reverse proxy is an option for TLS; answer: yes, reverse proxy is the central HTTPS routing layer, but certificates/trust still need a separate approach.

Related design artifact:

- `tickets/artifacts/2026-06-06-internal-dns-and-tailscale-naming/01-dns-tailscale-tls-design.md`

## Requirements

Must have:

- Proxmox-hosted managed service, preferably LXC.
- LAN/Tailscale-only access; no public port forwarding or public exposure.
- Nginx reverse proxy on ports 80/443.
- First proxied backend should be low-risk, recommended SearxNG at `192.168.0.133:8080`.
- Preserve direct backend access during MVP as rollback/fallback.
- Document DNS dependency and temporary hosts-file workaround if DNS service is not deployed first.
- Document certificate strategy and limitations.
- Record server-side changes in `docs/server-change-log.md`.

Nice to have:

- Internal CA certificate for trusted HTTPS on admin devices.
- Reusable Nginx site template for future services.
- Basic health-check page/command.
- Snapshot after base install and after first proxy route works.

Out of scope:

- Public internet exposure.
- Migrating all services.
- DNS provider automation.
- Full Tailscale deployment/ACL configuration.
- Replacing Vaultwarden's current TLS path in the first slice.

## Users / Stakeholders

- User/admin: wants clean internal service names and trusted HTTPS.
- Nimrod/Pi assistant: needs consistent service URLs for operations and documentation.
- Homelab services: Vaultwarden, SearxNG, Nextcloud, future apps.

## Proposed Design

### Placement

- New Proxmox LXC named `reverse-proxy`.
- Suggested CTID: next available at implementation time; verify both registry and live state.
- OS: Debian 13 standard LXC template.
- Resources: 1 vCPU, 512-1024 MB RAM, 8 GB disk.
- Network: `vmbr0`, DHCP initially; document observed IP and later add DHCP reservation/static plan.
- No public exposure; LAN-only until Tailscale is added.

### Runtime

- Host packages: `nginx`, `openssl`, `curl`, `ca-certificates`.
- Nginx listens on 80/443.
- `80` should redirect to `443` for configured service names, except perhaps local health endpoint.
- Per-service config files under `/etc/nginx/sites-available/` symlinked into `sites-enabled/`.

### First service route

Start with SearxNG because it is lower-risk than Vaultwarden:

```text
search.dropcutstud.io -> reverse-proxy LXC IP -> http://192.168.0.133:8080
```

Preserve direct fallback:

```text
http://192.168.0.133:8080/
```

### DNS during MVP

Preferred after dedicated DNS exists:

```text
search.dropcutstud.io A <reverse-proxy-ip>
```

Before dedicated DNS exists, test options:

- temporary client `/etc/hosts` entry on user workstation, or
- temporary OPNsense/Unbound host override if user approves, or
- direct curl with `--resolve search.dropcutstud.io:443:<reverse-proxy-ip>`.

### TLS strategy

MVP options:

1. **Temporary self-signed leaf certificate** for `search.dropcutstud.io`.
   - Fastest smoke test.
   - Browser warning expected.
   - Not final standard.

2. **Internal CA** for homelab services.
   - Better MVP standard.
   - Requires user to preserve CA private key safely and install root CA on trusted devices.
   - Should be handled carefully like backup recovery material.

Long-term preferred if user later approves DNS provider automation:

- Let's Encrypt DNS-01 for publicly trusted certificates without public service exposure.

Recommendation for first implementation:

- Use temporary self-signed cert only to validate reverse proxy routing.
- Then create a separate internal CA plan before treating TLS as user-friendly/standard.

## Infrastructure / Dependencies

- Proxmox host `buntbox01` / `192.168.0.88`.
- LXC template availability: Debian 13 standard template observed.
- Backend SearxNG: LXC 103 / `192.168.0.133:8080`.
- DNS service not yet deployed; use `curl --resolve` or temporary client hosts entry for MVP verification.
- Mutation lock required before creating/modifying Proxmox resources: `state/locks/proxmox.lock`.

## Security / Safety

- Do not expose proxy publicly.
- Do not route Vaultwarden through new proxy until SearxNG route is proven and rollback is clear.
- Do not store TLS private keys in git.
- If internal CA is created, CA private key must be stored outside git and preferably offline; document location by reference only.
- Keep backend direct access during MVP rollback window.
- Avoid logging secrets or sensitive headers.

## Backup / Rollback Plan

Before changes:

- Check live Proxmox state and registry.
- Acquire Proxmox lock.
- Use new LXC so rollback is simple destruction.

Rollback:

- Remove temporary DNS/hosts entries.
- Stop or destroy `reverse-proxy` LXC.
- Direct backend access remains unchanged.
- Delete temporary self-signed test certs if not needed.

Snapshots:

- Optional snapshot after base Nginx install.
- Optional snapshot after first service route works.

## Verification Plan

Base proxy:

```sh
systemctl is-active nginx
nginx -t
curl -kI https://127.0.0.1/
```

SearxNG route from proxy host:

```sh
curl -fsS http://192.168.0.133:8080/ >/dev/null
curl -k --resolve search.dropcutstud.io:443:<proxy-ip> https://search.dropcutstud.io/ -I
```

From LAN client/user:

- Add temporary hosts/DNS entry or use browser with DNS in place.
- Open `https://search.dropcutstud.io/`.
- Confirm SearxNG loads.

Production safety:

- Confirm direct `http://192.168.0.133:8080/` still works.
- Confirm no new WAN/public exposure was added.

## Open Questions / Approval Required

Infrastructure mutation approval required before implementation:

- Create new Proxmox LXC `reverse-proxy`.
- Install Nginx and create self-signed test certificate.
- Proxy SearxNG first.

User input helpful but not strictly required if approving defaults:

- Is SearxNG acceptable as the first proxied test service? Recommended yes.
- Is temporary self-signed TLS acceptable for the first smoke test? Recommended yes, with internal CA/Let's Encrypt decision later.
- Should DNS service be deployed before reverse proxy, or can we test with `curl --resolve`/temporary hosts entry first? Recommended test proxy first with `curl --resolve`, then deploy DNS.

## Acceptance Criteria

This spec is satisfied when:

- User approves or revises the implementation slice.
- Proxmox allocation details are verified immediately before mutation.
- `reverse-proxy` LXC is created and documented, or implementation is intentionally deferred.
- SearxNG can be reached through Nginx over HTTPS using `search.dropcutstud.io` resolution method.
- Direct SearxNG backend remains available as rollback.
- Registry, runbook, ticket, and server change log are updated.

## Decisions

- Central reverse proxy should be separate from dedicated DNS service.
- First backend should be low-risk; recommended SearxNG.
- No public exposure by default.
- Certificate/trust is separate from reverse proxy routing; self-signed is acceptable only as a temporary smoke-test path unless user chooses internal CA now.