mirror of
https://github.com/blackboxprogramming/BlackRoad-Operating-System.git
synced 2026-03-17 04:57:15 -05:00
a23ec040f1
Implements a declarative domain orchestrator that reads ops/domains.yaml and automatically applies DNS and forwarding configuration via GoDaddy and Cloudflare APIs. Features: - YAML-based configuration for all domains (ops/domains.yaml) - Python script to apply changes idempotently (ops/scripts/apply_domains.py) - GitHub Actions workflow to sync on YAML changes (sync-domains.yml) - Optional health check workflow (domain-health.yml) - Comprehensive documentation (docs/domains-overview.md) The system supports: - GoDaddy: DNS records and 301 forwarding - Cloudflare: DNS records (CNAME, A) All API credentials are read from GitHub secrets (GODADDY_API_KEY, GODADDY_API_SECRET, CLOUDFLARE_TOKEN).
64 lines
3.4 KiB
Markdown
64 lines
3.4 KiB
Markdown
# 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.
|