medusa/the_information_nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update tech_docs/its_the_new_style_design.md

Browse Source
This commit is contained in:
medusa
2025-08-04 16:20:45 -05:00
parent 0ba4abd1c1
commit 4a7aab7acb
1 changed files with 162 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

162
tech_docs/its_the_new_style_design.md
View File

@@ -1,3 +1,165 @@
──────────────────────────────
MyCorp “One-Box Wonder” – End-to-End Deployment Guide
──────────────────────────────
A **single Debian 12 server** becomes your DNS, DHCP, CA, and internal PKI authority.
The whole thing is **version-controlled copy-paste playbooks**—no tribal knowledge.
| Commit | 2024-06-XX |
| Author | you@… |
| Tag | v1.0-symmetry |
──────────────────────────────
0. TL;DR (30-second cheat-sheet)
```bash
git clone https://git.mycorp.net/infra/onebox-wonder
cd onebox-wonder && ./deploy.sh # walk away, coffee
```
Everything else below is **reference only**.
──────────────────────────────
1. Concepts & Naming Convention (never change)
| Element | Value / Pattern |
|-------------------|-----------------|
| Root domain | `mycorp.net` |
| Zone template | `<role>.mycorp.net` |
| Subnet template | `10.0.<vlan>.0/24` (or /28 for infra) |
| Split ranges | `.1–.126` static, `.129–.254` DHCP pool, `.127` broadcast |
| PTR mirror | `<vlan>.0.10.in-addr.arpa` |
| Hostname pattern | `<role>-<seq>.<zone>.mycorp.net` |
──────────────────────────────
2. Repository Layout (single Git repo)
```
onebox-wonder/
├── README.md
├── deploy.sh # idempotent; runs on fresh Debian 12
├── inventory/ # optional Ansible inventory
├── files/
│ ├── dnsmasq.d/
│ │ ├── 00-global.conf
│ │ ├── 10-lan.conf
│ │ ├── 20-dmz.conf
│ │ └── 99-static-maps.conf
│ ├── dnsmasq-static-hosts
│ ├── step-ca.service
│ └── acme-dns01.sh
├── scripts/
│ ├── gen-ptr.py # auto-creates reverse records
│ └── check-symmetry.py # lint before commit
└── docs/
└── CHANGELOG.md
```
──────────────────────────────
3. Hardware & VM Assumptions
| Resource | Minimum | Notes |
|----------|---------|-------|
| CPU | 1 vCPU | dnsmasq idle 99 % |
| RAM | 512 MB | 1 MB per 1000 leases |
| Disk | 8 GB | logs rotate weekly |
| NICs | 1 + VLAN sub-interfaces | or 3 physical ports |
──────────────────────────────
4. Bring-Up Script (deploy.sh – abridged)
```bash
#!/usr/bin/env bash
set -euo pipefail
HOST_IP=10.0.255.1
DEBIAN_FRONTEND=noninteractive
# 4.1 Base OS
apt update && apt -y upgrade
apt -y install dnsmasq curl wget git
systemctl disable --now systemd-resolved
ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
# 4.2 Install step-ca & acme.sh
curl -sSL https://dl.smallstep.com/cli/docs-ca-install/latest/step-ca_amd64.deb -o step.deb
dpkg -i step.deb && rm step.deb
curl -sSL https://get.acme.sh | sh -s email=admin@mycorp.net
# 4.3 Drop configs
rsync -a files/dnsmasq.d/ /etc/dnsmasq.d/
rsync -a files/dnsmasq-static-hosts /etc/
rsync -a files/step-ca.service /etc/systemd/system/
systemctl daemon-reload && systemctl enable --now step-ca
# 4.4 ACME hook + first cert
install -m 755 files/acme-dns01.sh /usr/local/bin/
~/.acme.sh/acme.sh --register-account --server https://$HOST_IP/acme/acme/directory
~/.acme.sh/acme.sh --issue -d ns.infra.mycorp.net --dns dns_aliases --dnssleep 3
# 4.5 Validation
dnsmasq --test && systemctl restart dnsmasq
dig +short ns.infra.mycorp.net @127.0.0.1 | grep -q "^10.0.255.1$"
echo "✅ One-Box Wonder is live"
```
──────────────────────────────
5. Per-Zone Configuration Templates
Copy `10-lan.conf`, rename to new VLAN, sed-replace:
```ini
# 10-lan.conf
domain=lan.mycorp.net,10.0.0.0/24
dhcp-range=set:lan,10.0.0.129,10.0.0.254,255.255.255.0,24h
dhcp-option=tag:lan,3,10.0.0.1
dhcp-option=tag:lan,6,10.0.255.1
ptr-record=0.0.10.in-addr.arpa,lan.mycorp.net
```
──────────────────────────────
6. Static Hosts & PTR Automation
Run `./scripts/gen-ptr.py` before every commit.
Example output appended to `dnsmasq-static-hosts`:
```
10.0.20.10 printer-01.lan.mycorp.net
ptr-record=10.20.0.10.in-addr.arpa,printer-01.lan.mycorp.net
```
──────────────────────────────
7. Day-2 Operations
| Task | Command |
|------|---------|
| Add subnet | `cp 10-lan.conf 40-cameras.conf && sed -i 's/0/40/g' 40-cameras.conf && git commit -am "add camera vlan"` |
| Re-issue cert | `acme.sh --renew -d host.zone.mycorp.net` |
| Hot backup | nightly `rsync -a /etc/dnsmasq* /var/backups/` |
| Validate symmetry | `./scripts/check-symmetry.py` (CI job) |
──────────────────────────────
8. Migration Escape Hatches
| Trigger | Plan |
|---------|------|
| > 500 leases /24 | Split into second dnsmasq or migrate DHCP to KEA (keeps DNS) |
| Need DNSSEC views | Insert Unbound in front of dnsmasq, forward internal zones |
| Multi-site | Git push → Ansible pull on second site; subnets remain identical |
──────────────────────────────
9. Single-Page Runbook (laminate & tape to rack)
```
Need a new VLAN?
1. echo "VLAN=50 NAME=lab" >> inventory/vlans.csv
2. ./scripts/generate-zone.sh 50 lab
3. git commit -am "VLAN 50 lab"
4. ./deploy.sh
```
──────────────────────────────
10. Final Commit Message
```
feat: v1.0 – symmetry-first DNS/DHCP/CA stack
- single dnsmasq instance, 4 conf files, 1 static hosts file
- integrated step-ca + acme.sh for internal TLS
- repo contains all automations, zero external state
```
Done.
Clone, `./deploy.sh`, go back to real work.
---
You’re right—let’s be brutally honest about the **actual** longevity instead of the usual consultant-speak. You’re right—let’s be brutally honest about the **actual** longevity instead of the usual consultant-speak.
### Reality check on the 10 % that covers 95 % ### Reality check on the 10 % that covers 95 %