# Story 12.12: Configure Custom Domain for Read the Docs (docs.fapilog.dev)

**Status:** Complete
**Priority:** P1 (High)
**Depends on:** None (but should complete before 12.11 for correct canonical URLs)
**Epic:** 12.0 Cookbook (SEO-Driven Documentation)

---

## Context / Background

fapilog documentation is hosted on Read the Docs at `fapilog.readthedocs.io`. Using a custom domain (`docs.fapilog.dev`) provides:

- **Brand consistency** - URLs match the project name
- **SEO portability** - Link equity stays with the domain if we migrate platforms
- **Professional appearance** - Custom domain signals a mature project

The domain `fapilog.dev` is already registered. This story configures `docs.fapilog.dev` as a subdomain pointing to RTD.

---

## Scope (In / Out)

### In Scope

- Configure DNS CNAME record for `docs.fapilog.dev`
- Configure custom domain in RTD dashboard
- Verify SSL certificate provisioning
- Update any hardcoded references to `fapilog.readthedocs.io`
- Document the setup for future maintainers

### Out of Scope

- Domain registration (already owned)
- Email/MX record configuration
- Other subdomains (api.fapilog.dev, etc.)
- CDN or additional caching layers

---

## Acceptance Criteria

### AC1: DNS Configured Correctly

**Description:** CNAME record points docs.fapilog.dev to RTD.

**Validation:**
```bash
# Verify CNAME record
dig docs.fapilog.dev CNAME +short
# Expected: readthedocs.io. (or specific RTD hostname)

# Alternative check
nslookup docs.fapilog.dev
```

### AC2: RTD Custom Domain Active

**Description:** RTD dashboard shows custom domain as verified and active.

**Validation:**
- RTD Admin → Domains shows `docs.fapilog.dev` as verified
- No SSL warnings or errors
- Canonical URL setting uses custom domain

### AC3: SSL Certificate Valid

**Description:** HTTPS works with valid certificate.

**Validation:**
```bash
# Check SSL certificate
curl -vI https://docs.fapilog.dev 2>&1 | grep -E "(SSL|subject|issuer)"

# Verify no certificate warnings
curl -s https://docs.fapilog.dev > /dev/null && echo "SSL OK"
```

### AC4: Documentation Accessible

**Description:** All documentation pages load correctly on new domain.

**Validation:**
```bash
# Homepage loads
curl -s -o /dev/null -w "%{http_code}" https://docs.fapilog.dev/
# Expected: 200

# Versioned path works
curl -s -o /dev/null -w "%{http_code}" https://docs.fapilog.dev/en/stable/
# Expected: 200

# Deep page works
curl -s -o /dev/null -w "%{http_code}" https://docs.fapilog.dev/en/stable/getting-started/
# Expected: 200
```

### AC5: Old URL Redirects (Optional but Recommended)

**Description:** `fapilog.readthedocs.io` redirects to `docs.fapilog.dev`.

**Validation:**
```bash
curl -I https://fapilog.readthedocs.io/ 2>&1 | grep -i location
# Expected: Location: https://docs.fapilog.dev/...
```

Note: RTD may handle this automatically when custom domain is set as canonical.

### AC6: References Updated

**Description:** Hardcoded URLs in repo point to new domain.

**Validation:**
```bash
# No references to old RTD URL (except historical docs)
grep -r "fapilog.readthedocs.io" --include="*.md" --include="*.py" --include="*.rst" \
  | grep -v CHANGELOG | grep -v "docs/stories"
# Expected: No results (or only intentional references)
```

---

## Implementation Notes

### Step 1: DNS Configuration

Add CNAME record in your DNS provider (wherever fapilog.dev is registered):

```
Type:  CNAME
Name:  docs
Value: readthedocs.io.
TTL:   3600 (or default)
```

Some providers may require:
```
docs.fapilog.dev. CNAME readthedocs.io.
```

### Step 2: RTD Dashboard Configuration

1. Log in to Read the Docs
2. Go to project → Admin → Domains
3. Click "Add Domain"
4. Enter: `docs.fapilog.dev`
5. Check "Canonical" checkbox (makes this the primary URL)
6. Save and wait for verification

RTD will:
- Verify DNS is configured correctly
- Provision SSL certificate via Let's Encrypt
- Set up redirects from `fapilog.readthedocs.io`

### Step 3: Update References

Files likely needing updates:

```
README.md - documentation links
pyproject.toml - project URLs
docs/conf.py - html_baseurl if set
.github/ISSUE_TEMPLATE/* - doc links
CONTRIBUTING.md - doc links
```

Search pattern:
```bash
grep -rn "fapilog.readthedocs.io" .
```

### Step 4: Verify and Monitor

- Check RTD dashboard for SSL status
- Test all AC validation commands
- Monitor for 24-48 hours (DNS propagation, SSL renewal)

---

## Tasks

### Phase 1: DNS Setup

- [ ] Log in to DNS provider for fapilog.dev
- [ ] Add CNAME record: `docs` → `readthedocs.io`
- [ ] Verify DNS propagation (may take up to 48 hours, usually minutes)

### Phase 2: RTD Configuration

- [ ] Add custom domain in RTD dashboard
- [ ] Mark as canonical domain
- [ ] Wait for SSL certificate provisioning
- [ ] Verify domain shows as "verified" in RTD

### Phase 3: Reference Updates

- [ ] Search for hardcoded `fapilog.readthedocs.io` URLs
- [ ] Update README.md
- [ ] Update pyproject.toml project URLs
- [ ] Update docs/conf.py if needed
- [ ] Update any GitHub templates

### Phase 4: Verification

- [ ] Test homepage loads on new domain
- [ ] Test versioned URLs work
- [ ] Test deep links work
- [ ] Verify SSL certificate valid
- [ ] Verify old URL redirects to new domain

### Phase 5: Documentation

- [ ] Document DNS setup in contributing guide or internal docs
- [ ] Note the domain registrar and RTD account for future reference

---

## Tests

### Manual Verification

- [ ] `dig docs.fapilog.dev` returns CNAME to readthedocs.io
- [ ] `https://docs.fapilog.dev` loads with valid SSL
- [ ] All documentation sections accessible
- [ ] Old RTD URL redirects appropriately

### Automated (CI)

- [ ] Link checker validates docs.fapilog.dev URLs
- [ ] No broken links in README or docs

---

## Definition of Done

### Infrastructure Complete

- [ ] DNS CNAME configured and propagated
- [ ] RTD custom domain verified and canonical
- [ ] SSL certificate active and auto-renewing

### References Updated

- [ ] All repo documentation links use new domain
- [ ] PyPI project URL uses new domain

### Verified

- [ ] All pages accessible on new domain
- [ ] Old domain redirects correctly
- [ ] No mixed content or SSL warnings

---

## Risks / Rollback

### Risks

1. **Risk:** DNS propagation delays
   - **Mitigation:** Plan for 24-48 hour window; old URL continues working

2. **Risk:** SSL certificate provisioning fails
   - **Mitigation:** RTD handles this automatically; contact support if stuck

3. **Risk:** Broken links during transition
   - **Mitigation:** RTD maintains redirects from old URL; update refs after verification

### Rollback Plan

1. Remove custom domain from RTD dashboard
2. (Optionally) Remove DNS CNAME record
3. Revert any URL reference changes in repo

Old `fapilog.readthedocs.io` URL will continue working throughout and after rollback.

---

## Dependencies

- **Enables:** 12.11 Sitemap Generation - canonical URLs should use `docs.fapilog.dev`
- **Related:** 12.0 Cookbook Epic - SEO foundation

---

## Notes

### DNS Provider

Document which provider manages fapilog.dev DNS for future reference:
- Provider: _____________
- Account: _____________

### RTD Account

- RTD organization/user: _____________
- Project slug: `fapilog`

---

## Change Log

| Date | Change | Author |
|------|--------|--------|
| 2026-01-21 | Initial draft | Claude |
