# DNS Requirements for BasicStack Services **Last Updated:** 2026-07-06 ## Overview This document lists all DNS records required for BasicStack services running on the k3s cluster. ## Primary Domain: basicstack.de ### A Records (HTTP/HTTPS Services) All HTTP/HTTPS services are accessed via Traefik LoadBalancer. Point DNS records to one or more of the following IPs: **Recommended Target IPs:** - `178.105.17.239` (k3s-cp-1 control-plane - most stable) - `10.42.1.2` (k3s-worker-1 - if using private network routing) - `10.42.1.3` (k3s-worker-2 - if using private network routing) - `10.42.1.5` (k3s-worker-3 - if using private network routing) ### Required DNS A/CNAME Records | Hostname | Type | Target | Service | Port(s) | |----------|------|--------|---------|---------| | basicstack.org | A | 178.105.17.239 | BasicStack website | 443 | | www.basicstack.org | A | 178.105.17.239 | BasicStack website | 443 | | paperclip.basicstack.de | A | 178.105.17.239 | Paperclip Platform | 443 | | mail.basicstack.de | A | 178.105.17.239 | Stalwart Webmail | 443 | | forgejo.basicstack.de | A | 178.105.17.239 | Git Hosting | 443 | | directus.basicstack.de | A | 178.105.17.239 | CMS | 443 | | books.basicstack.de | A | 178.105.17.239 | BookStack Wiki | 443 | | auth.basicstack.de | A | 178.105.17.239 | Pocket ID (SSO) | 443 | | nextcloud.basicstack.de | A | 178.105.17.239 | File Storage | 443 | | grafana.basicstack.de | A | 178.105.17.239 | Monitoring | 443 | | prometheus.basicstack.de | A | 178.105.17.239 | Metrics | 443 | | alertmanager.basicstack.de | A | 178.105.17.239 | Alerting | 443 | | planka.basicstack.de | A | 178.105.17.239 | Task Board | 443 | | vaultwarden.basicstack.de | A | 178.105.17.239 | Password Manager | 443 | | passbolt.basicstack.de | A | 178.105.17.239 | Password Manager | 443 | | opencloud.basicstack.de | A | 178.105.17.239 | OpenCloud | 443 | | registry.basicstack.de | A | 178.105.17.239 | Container Registry | 443 | | pangolin.basicstack.de | A | 178.105.17.239 | Pangolin (Plausible Analytics) | 443 | ### Mail-Specific DNS Records #### MX Records ``` basicstack.de. 3600 IN MX 10 mail.basicstack.de. ``` #### Mail Server A Record ``` mail.basicstack.de. 3600 IN A 178.105.17.239 ``` #### SPF Record (TXT) ``` basicstack.de. 3600 IN TXT "v=spf1 a:mail.basicstack.de ~all" ``` Explanation: - `v=spf1`: SPF version 1 - `a:mail.basicstack.de`: Allow mail from the IP of mail.basicstack.de - `~all`: Soft fail for all other sources #### DKIM Record (TXT) **Important:** Replace `` with actual DKIM public key from Stalwart configuration. ``` default._domainkey.basicstack.de. 3600 IN TXT "v=DKIM1; k=rsa; p=" ``` To get the DKIM public key: ```bash kubectl exec -n stalwart deploy/stalwart -- cat /app/dkim/default.public.pem ``` #### DMARC Record (TXT) ``` _dmarc.basicstack.de. 3600 IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@basicstack.de" ``` Explanation: - `v=DMARC1`: DMARC version 1 - `p=quarantine`: Policy for failed messages (quarantine them) - `rua`: Email address for aggregate reports #### PTR Record (Reverse DNS) **Important:** This must be configured at Hetzner for the server's public IP. ``` 239.17.105.178.in-addr.arpa. IN PTR mail.basicstack.de. ``` Request this from Hetzner Cloud for IP `178.105.17.239`. ## Wildcard DNS (Alternative) Instead of individual A records, you can use a wildcard: ``` *.basicstack.de. 3600 IN A 178.105.17.239 ``` **Pros:** - Simpler DNS management - Automatic coverage for new services **Cons:** - Less control over individual service routing - Potential security implications (all subdomains resolve) ## DNS Propagation and TTL **Recommended TTL:** 3600 seconds (1 hour) **When changing DNS:** 1. Lower TTL to 300 seconds (5 minutes) at least 24 hours before the change 2. Make the DNS change 3. Wait for propagation (typically 5-15 minutes with low TTL) 4. Verify with: `dig @8.8.8.8` 5. Raise TTL back to 3600 seconds ## DNS Providers ### Hetzner DNS If using Hetzner DNS: 1. Access via Hetzner Cloud Console or `hcloud` CLI 2. Zone: `basicstack.de` 3. Can manage via API or web interface ### Manual Verification Check DNS records: ```bash # Check A record dig basicstack.de @8.8.8.8 +short # Check MX record dig basicstack.de MX @8.8.8.8 +short # Check TXT records (SPF, DKIM, DMARC) dig basicstack.de TXT @8.8.8.8 +short dig default._domainkey.basicstack.de TXT @8.8.8.8 +short dig _dmarc.basicstack.de TXT @8.8.8.8 +short # Check specific subdomain dig mail.basicstack.de @8.8.8.8 +short ``` ## Troubleshooting DNS Issues ### Service Not Accessible 1. **Check DNS resolution:** ```bash dig @8.8.8.8 ``` 2. **Verify LoadBalancer IPs:** ```bash kubectl get svc -n kube-system traefik ``` 3. **Check Traefik ingress:** ```bash kubectl get ingress -A | grep ``` 4. **Test from within cluster:** ```bash kubectl run -it --rm test --image=curlimages/curl --restart=Never -- curl -I https:// ``` ### Mail Delivery Issues 1. **Check MX record:** ```bash dig basicstack.de MX @8.8.8.8 ``` 2. **Verify SMTP port accessibility:** ```bash telnet mail.basicstack.de 25 ``` 3. **Check SPF/DKIM/DMARC:** ```bash dig basicstack.de TXT @8.8.8.8 dig default._domainkey.basicstack.de TXT @8.8.8.8 dig _dmarc.basicstack.de TXT @8.8.8.8 ``` 4. **Verify reverse DNS (PTR):** ```bash dig -x 178.105.17.239 @8.8.8.8 ``` ## DNS Configuration Checklist Before deploying a new service: - [ ] Add A record for service hostname - [ ] Verify DNS propagation (dig) - [ ] Create Kubernetes Ingress resource - [ ] Configure cert-manager Certificate - [ ] Test HTTPS accessibility - [ ] Update this document For mail services, additionally: - [ ] Configure MX record - [ ] Configure SPF record - [ ] Generate and configure DKIM keys - [ ] Configure DMARC record - [ ] Request PTR record from Hetzner - [ ] Test mail delivery with external tool (mail-tester.com) ## Related Documentation - [Network Architecture](NETWORK_ARCHITECTURE.md) - [Stalwart Mail Setup](../../apps/stalwart/README.md) - [K3S Operations Guide](../K3S_OPERATIONS.md) ## Changelog | Date | Change | Author | |------|--------|--------| | 2026-07-06 | Initial DNS requirements documentation | CTO (DEV-225) |