blackroad-operating-system/docs/domains-overview.md

Domain Management Overview

This repository includes a universal domain orchestrator that allows you to declare all of your domains in a single YAML file and sync them to your DNS providers automatically. The goal is to avoid manual updates in registrar dashboards by defining a clear desired state and letting automation converge on it.

Configuration File (ops/domains.yaml)

The ops/domains.yaml file lists each domain or subdomain with the following fields:

• name: The fully qualified domain or subdomain (e.g. blackroad.systems, os.blackroad.systems).
• type: "root" for an apex domain or "subdomain" for a subdomain.
• provider: Which registrar/DNS provider the domain lives in (godaddy or cloudflare).
• mode:
  • forward – perform a 301 (permanent) redirect to another URL.
  • dns – create or update a DNS record (CNAME or A).
• forward_to (only for forward): The destination URL to forward to.
• forwarding_type (optional): HTTP status code for forwarding (301 by default).
• record (only for dns): A mapping with type (CNAME or A) and value (target hostname or IP).
• healthcheck (optional): Set to true to enable periodic health checks in the optional workflow.

Add as many entries as needed; the script processes them sequentially.

Domain Sync Script (ops/scripts/apply_domains.py)

This Python script:

1. Parses ops/domains.yaml.
2. For GoDaddy domains:
   • Uses the GoDaddy API to set forwarding rules or DNS records.
   • A permanent 301 redirect tells search engines to treat the destination as the canonical URL.
3. For Cloudflare domains:
   • Finds the zone ID for the root domain.
   • Creates or updates DNS records using the Cloudflare API, which supports PUT/PATCH requests to overwrite DNS entries.
4. Prints a summary of actions taken; if nothing changed, it reports that the record is up to date.

All credentials (GoDaddy key/secret and Cloudflare token) are read from environment variables. Never hard‑code secrets. Set them as GitHub repository secrets (Settings → Secrets and variables → Actions).

GitHub Actions Workflows

sync-domains.yml

• Runs on pushes to main where ops/domains.yaml changes, or via manual trigger.
• Checks out the repo, installs Python dependencies, and runs the sync script.
• Uses secrets to authenticate to GoDaddy and Cloudflare.
• Annotates logs with changes so you can see which domains were updated.

domain-health.yml (optional)

• Runs every six hours (or manually).
• Reads ops/domains.yaml and performs an HTTP GET against any domain marked healthcheck: true.
• Logs whether the domain is reachable; you can extend it to open GitHub Issues on repeated failures.

How To Add or Modify Domains

1. Open ops/domains.yaml and add a new entry for each domain or subdomain you own.
2. Specify its provider, mode, and either forward_to or a DNS record.
3. Commit and push your changes to main.
4. Ensure the following secrets are configured in GitHub:
   • GODADDY_API_KEY, GODADDY_API_SECRET
   • CLOUDFLARE_TOKEN
5. Run the Sync Domains workflow manually (Actions → Sync Domains → Run workflow) or wait for the push trigger.
6. Verify your DNS or forwarding settings with dig or by visiting the domains.

By following this process, you maintain a single source of truth for all of your domains and eliminate the need to log into registrar dashboards for each change.