stack.basicstack.de/infrastructure/networking/DNS_REQUIREMENTS.md

# 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 |

### 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 `<public-key>` with actual DKIM public key from Stalwart configuration.

```
default._domainkey.basicstack.de.  3600  IN  TXT  "v=DKIM1; k=rsa; p=<public-key>"
```

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 <hostname> @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 <hostname> @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 <hostname>
   ```

4. **Test from within cluster:**
   ```bash
   kubectl run -it --rm test --image=curlimages/curl --restart=Never -- curl -I https://<hostname>
   ```

### 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) |