hearth/docs/architecture.md

Hearth Architecture

Minimal infrastructure for ~1 user at ~$7.50/month.

Overview

                              Internet
                                  |
                     +------------+------------+
                     |     Elastic IP          |
                     |    3.218.167.115        |
                     +------------+------------+
                                  |
              +-------------------+-------------------+
              |                   |                   |
           :22 SSH           :53 DNS            :443 HTTPS
           (Git)            (PowerDNS)          (Traefik)
              |                   |                   |
              +-------------------+-------------------+
                                  |
                     +------------+------------+
                     |   EC2 t4g.small (ARM)   |
                     |   Amazon Linux 2023     |
                     |   20GB gp3 EBS          |
                     +------------+------------+
                                  |
                     +------------+------------+
                     |         k3s             |
                     +-------------------------+
                     |                         |
              +------+------+    +------+------+
              |   traefik   |    |     dns     |
              |  namespace  |    |  namespace  |
              +-------------+    +-------------+
              | Traefik     |    | PowerDNS    |
              | (ingress)   |    | (auth DNS)  |
              +-------------+    +-------------+
                     |
              +------+------+
              |   forgejo   |
              |  namespace  |
              +-------------+
              | Forgejo     |
              | (git host)  |
              +-------------+

Components

EC2 Instance

• Type: t4g.small (2 vCPU, 2GB RAM, ARM64)
• Pricing: Spot instance (~$0.007/hr)
• Storage: 20GB gp3 EBS (encrypted)
• OS: Amazon Linux 2023

k3s

Lightweight Kubernetes distribution. Single-node cluster with:

• Built-in containerd
• Local storage
• No Traefik (disabled, using our own)

Traefik

Ingress controller with:

• HTTP → HTTPS redirect
• Let's Encrypt ACME (HTTP-01 challenge)
• TCP routing for Git SSH

PowerDNS

Authoritative DNS server for managed domains:

• superviber.com
• muffinlabs.ai
• letemcook.com
• appbasecamp.com
• thanksforborrowing.com
• alignment.coop

Uses SQLite backend, data persisted to /data/powerdns.

Forgejo

Self-hosted Git forge (Gitea fork):

• Web UI at git.beyondtheuniverse.superviber.com
• Git SSH on port 22
• SQLite database
• Data persisted to /data/forgejo

Storage

All persistent data on host filesystem:

/data/
├── forgejo/        # Forgejo repos and database
│   └── gitea/
│       ├── gitea.db
│       └── conf/app.ini
└── powerdns/       # PowerDNS database
    └── pdns.sqlite3

Networking

Security Group

Port	Protocol	Source	Purpose
22	TCP	0.0.0.0/0	Git SSH
53	UDP/TCP	0.0.0.0/0	DNS
80	TCP	0.0.0.0/0	HTTP (redirect)
443	TCP	0.0.0.0/0	HTTPS
2222	TCP	Admin IPs	Admin SSH
6443	TCP	Admin IPs	Kubernetes API

DNS Flow

User query → GoDaddy NS lookup → ns1/ns2.superviber.com
                                       ↓
                              Glue record: 3.218.167.115
                                       ↓
                              PowerDNS (port 53)
                                       ↓
                              Zone lookup → Response

Cost Breakdown

Component	Monthly
EC2 t4g.small spot	~$5.00
EBS gp3 20GB	~$1.60
Elastic IP	~$0.50
S3 backups	~$0.50
Total	~$7.50

Backups

Daily cron job at 3 AM:

1. SQLite backup of Forgejo database
2. k3s state backup
3. Upload to S3 (hearth-backups bucket)
4. 60-day retention with lifecycle policy

Limitations

This is personal infrastructure, not production-grade:

• No HA: Single point of failure
• Spot interruption: Instance may be reclaimed (data persists on EBS)
• No monitoring: Basic healthchecks only
• Single region: us-east-1 only

Future Work

See RFC 0003 for planned improvements:

• HA DNS with separate instance
• DNSSEC
• DNS-over-HTTPS
• PowerDNS-Admin UI