80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# Existing `.loc.cc` Domain Recovery and Tunnel Routing
|
|
|
|
## Diagnostic order
|
|
|
|
1. Authenticate to the account that owns the domain.
|
|
2. `GET /api/domains` and locate the exact `full_domain`.
|
|
3. Record `id`, `status`, `suspend_reason`, `first_failed_at`, `dns_synced`, and `scan_summary`.
|
|
4. `GET /api/domain-scans/{id}` to distinguish DNS, HTTP, and TLS failures.
|
|
5. `GET /api/dns/{id}/records`; check `synced_to_powerdns` and `sync_error` per record.
|
|
6. If provider state may be stale, `POST /api/dns/{id}/records/sync-from-powerdns`.
|
|
7. Query `ns1.nodelook.com` and `ns2.nodelook.com` directly, then public resolvers.
|
|
8. Test public HTTP/TLS and application endpoints from outside the origin network.
|
|
|
|
## Important failure signatures
|
|
|
|
### Domain resolves but remains suspended
|
|
|
|
Typical fields:
|
|
|
|
```json
|
|
{
|
|
"status": "suspended",
|
|
"suspend_reason": "Domain down for 7 days",
|
|
"scan_summary": {
|
|
"dns_status": "resolved",
|
|
"http_status": "offline",
|
|
"ssl_status": "invalid"
|
|
}
|
|
}
|
|
```
|
|
|
|
This is not a registration failure. Restore externally reachable HTTP/TLS and wait for/trigger only a documented health scan. Do not invent an unsuspend endpoint.
|
|
|
|
### Cloudflare Tunnel error 1001
|
|
|
|
Symptoms:
|
|
|
|
- tunnel connector is healthy;
|
|
- hostname exists in local ingress;
|
|
- DNS CNAME points to `<uuid>.cfargotunnel.com`;
|
|
- HTTP via Cloudflare returns `error code: 1001` or TLS cannot be provisioned.
|
|
|
|
Interpretation: the hostname was not routed from a Cloudflare-managed zone/account. A raw external CNAME is insufficient. Confirm the parent zone is available through `/zones` and that `cloudflared tunnel route dns` or the equivalent API route succeeds before relying on this design.
|
|
|
|
## DNS record safety
|
|
|
|
- Apex CNAME/ALIAS commonly conflicts with MX and TXT records.
|
|
- Preserve mail and domain-verification records unless the user explicitly accepts losing them.
|
|
- A dedicated `api` hostname avoids apex coexistence conflicts but not Cloudflare ownership constraints.
|
|
- After mutation, verify both API state and authoritative DNS. A successful POST alone is not completion.
|
|
|
|
## Static ngrok fallback discovered from local state
|
|
|
|
When a vanity domain cannot be published, search account inventories and prior sessions for an assigned static ngrok hostname before settling for a random `ngrok-free.app` URL.
|
|
|
|
Credential distinction:
|
|
|
|
- agent `authtoken` is enough to start a tunnel on a static hostname already assigned to that account;
|
|
- an ngrok `api_key` is only needed for management commands such as reserved-domain listing/creation.
|
|
|
|
Operational ownership test:
|
|
|
|
```powershell
|
|
ngrok http --domain=<assigned-hostname> 8080 --authtoken <authtoken>
|
|
```
|
|
|
|
Require the log to show `started tunnel` with the exact hostname, then test the public routes. Persist the exact command in startup automation and update all URL consumers. Do not describe this fallback as the vanity domain itself.
|
|
|
|
## Completion gate
|
|
|
|
Report a stable domain only when all are true:
|
|
|
|
- authoritative and public DNS agree, or the static tunnel agent confirms the exact assigned hostname;
|
|
- TLS certificate is valid for the hostname;
|
|
- `/health` returns 200 externally;
|
|
- `/v1/models` or the product's real API route returns the expected authenticated/public response;
|
|
- bot/docs/config/tests references use the same verified hostname;
|
|
- the affected application was restarted and its live URL configuration read back;
|
|
- a restart/autostart path for the tunnel or reverse proxy is present and tested.
|