137 lines
4.2 KiB
Markdown
137 lines
4.2 KiB
Markdown
# Adding a New Subdomain
|
|
|
|
Every new subdomain needs to be registered in three places. Miss one and either
|
|
the DNS won't auto-update when your WAN IP changes, or the service won't be reachable.
|
|
|
|
---
|
|
|
|
## The Three Places
|
|
|
|
| # | Where | What it does |
|
|
|---|-------|-------------|
|
|
| 1 | **Cloudflare DNS** | Creates the A record |
|
|
| 2 | **DDNS compose file** | Keeps the A record pointed at your current WAN IP |
|
|
| 3 | **NPM proxy host** | Routes HTTPS traffic to the right container |
|
|
|
|
---
|
|
|
|
## Step 1 — Cloudflare DNS
|
|
|
|
Create the A record via the Cloudflare dashboard or API.
|
|
|
|
**Proxied (orange cloud)** — use for all standard HTTP/HTTPS services:
|
|
```bash
|
|
curl -s -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
|
|
-H "Authorization: Bearer $CF_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"type":"A","name":"myservice.vish.gg","content":"1.2.3.4","proxied":true}'
|
|
```
|
|
|
|
**Direct (grey cloud)** — use only for non-HTTP protocols (TURN, SSH, game servers, WebRTC):
|
|
```bash
|
|
# same but "proxied":false
|
|
```
|
|
|
|
**Zone IDs:**
|
|
| Domain | Zone ID |
|
|
|--------|---------|
|
|
| `vish.gg` | `4dbd15d096d71101b7c0c6362b307a66` |
|
|
| `thevish.io` | `11681f1c93ca32f56a0c41973e02b6f9` |
|
|
| `crista.love` | *(check Cloudflare dashboard)* |
|
|
|
|
The content IP doesn't matter much if it's proxied — the DDNS updater will overwrite it.
|
|
Use a placeholder like `1.2.3.4` for now.
|
|
|
|
---
|
|
|
|
## Step 2 — DDNS Compose File
|
|
|
|
Add the domain to the correct host's DDNS `DOMAINS=` list. Pick the host whose
|
|
WAN IP the service is behind:
|
|
|
|
| Host | File | Use when |
|
|
|------|------|----------|
|
|
| Atlantis / Calypso (home) | `hosts/synology/atlantis/dynamicdnsupdater.yaml` | Service is behind home WAN IP |
|
|
| concord-nuc | `hosts/physical/concord-nuc/dyndns_updater.yaml` | API/direct-access on concord-nuc |
|
|
| Seattle VPS | `hosts/vms/seattle/ddns-updater.yaml` | Service is on the Seattle VPS |
|
|
| Guava (crista.love) | `hosts/physical/guava/portainer_yaml/dynamic_dns.yaml` | crista.love subdomains |
|
|
|
|
For a standard proxied service on Atlantis/Calypso, edit `dynamicdnsupdater.yaml`
|
|
and append your domain to the `ddns-vish-proxied` service:
|
|
|
|
```yaml
|
|
- DOMAINS=...,myservice.vish.gg # add here, keep comma-separated
|
|
- PROXIED=true
|
|
```
|
|
|
|
For an unproxied (direct) domain, use the `ddns-thevish-unproxied` service or
|
|
create a new service block with `PROXIED=false`.
|
|
|
|
Then redeploy the stack via Portainer (Atlantis, stack `dyndns-updater-stack`, ID 613):
|
|
```bash
|
|
# Portainer API — or just use the UI: Stacks → dyndns-updater-stack → Editor → Update
|
|
```
|
|
|
|
---
|
|
|
|
## Step 3 — NPM Proxy Host
|
|
|
|
Add a proxy host at **http://npm.vish.gg:81** (or `http://192.168.0.250:81`):
|
|
|
|
1. **Hosts → Proxy Hosts → Add Proxy Host**
|
|
2. **Domain names**: `myservice.vish.gg`
|
|
3. **Forward hostname/IP**: container name or LAN IP of the service
|
|
4. **Forward port**: the service's internal port
|
|
5. **SSL tab**: Request a new Let's Encrypt cert, enable **Force SSL**
|
|
6. *(Optional)* **Advanced tab**: add Authentik forward-auth snippet if SSO is needed
|
|
|
|
---
|
|
|
|
## Exceptions — services that skip Step 3
|
|
|
|
If your subdomain doesn't need an NPM proxy rule (direct-access APIs, WebRTC,
|
|
services with their own proxy), add it to `DDNS_ONLY_EXCEPTIONS` in
|
|
`.gitea/scripts/dns-audit.py` so the daily audit doesn't flag it:
|
|
|
|
```python
|
|
DDNS_ONLY_EXCEPTIONS = {
|
|
...
|
|
"myservice.vish.gg", # reason: direct access / own proxy
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Step 4 — Verify
|
|
|
|
Run the DNS audit to confirm everything is wired up:
|
|
|
|
```bash
|
|
cd /home/homelab/organized/repos/homelab
|
|
CF_TOKEN=<your-cf-token> \
|
|
NPM_EMAIL=<npm-admin-email> \
|
|
NPM_PASSWORD="REDACTED_PASSWORD" \
|
|
python3 .gitea/scripts/dns-audit.py
|
|
```
|
|
|
|
The CF token is stored in Portainer as `CLOUDFLARE_API_TOKEN` on the DDNS stacks.
|
|
NPM credentials are stored as `NPM_EMAIL` / `NPM_PASSWORD` Gitea Actions secrets.
|
|
The audit also runs automatically every day at 08:00 UTC — check the Gitea Actions tab.
|
|
|
|
Expected output:
|
|
```
|
|
✅ All N DDNS domains OK, CF and DDNS are in sync
|
|
```
|
|
|
|
---
|
|
|
|
## Commit the changes
|
|
|
|
```bash
|
|
git add hosts/synology/atlantis/dynamicdnsupdater.yaml # (whichever file you edited)
|
|
git commit -m "Add myservice.vish.gg subdomain"
|
|
git push
|
|
```
|
|
|
|
Portainer will pick up the DDNS change on the next git redeploy, or trigger it manually.
|