// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2025 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>

= GitHub Pages Setup for axel-protocol.org
:toc: left
:toclevels: 3
:icons: font

This guide explains how to set up `axel-protocol.org` to serve the AXEL Protocol website via GitHub Pages.

== Prerequisites

* Domain registrar account (Cloudflare Registrar, Namecheap, Gandi, etc.)
* Access to hyperpolymath/axel-protocol GitHub repo
* DNS configuration access

== Step 1: Register Domain

=== Option A: Cloudflare Registrar (Recommended)

*Pros*: At-cost pricing (~$9/year for .org), built-in DNS, DDoS protection

[source,bash]
----
# 1. Go to Cloudflare Dashboard > Domain Registration
# 2. Search for "axel-protocol.org"
# 3. Purchase (requires Cloudflare account with payment method)
# 4. Domain auto-configured in Cloudflare DNS
----

=== Option B: Namecheap

*Pros*: Easy, reliable, ~$13/year

[source,bash]
----
# 1. Go to https://namecheap.com
# 2. Search "axel-protocol.org"
# 3. Add to cart, checkout
# 4. After purchase, go to Dashboard > Manage > Advanced DNS
----

=== Option C: Gandi

*Pros*: Privacy-focused, no upsells, ~$15/year

[source,bash]
----
# 1. Go to https://gandi.net
# 2. Search "axel-protocol.org"
# 3. Purchase
# 4. Go to Domain > DNS Records
----

== Step 2: Enable GitHub Pages

=== 2.1 Configure Repo Settings

[source,bash]
----
# Via GitHub CLI
cd ~/Documents/hyperpolymath-repos/axel-protocol
gh repo edit --enable-pages --pages-branch main --pages-path /

# Or via web UI:
# 1. Go to https://github.com/hyperpolymath/axel-protocol/settings/pages
# 2. Source: Deploy from branch
# 3. Branch: main
# 4. Path: / (root)
# 5. Click Save
----

=== 2.2 Verify Deployment

After enabling, GitHub will deploy your site to:

----
https://hyperpolymath.github.io/axel-protocol/
----

*Wait 2-3 minutes*, then visit the URL to confirm `index.html` is live.

== Step 3: Configure Custom Domain

=== 3.1 Add Custom Domain in GitHub

[source,bash]
----
# Via GitHub CLI
gh repo edit --custom-domain axel-protocol.org

# Or via web UI:
# 1. Go to https://github.com/hyperpolymath/axel-protocol/settings/pages
# 2. Custom domain: axel-protocol.org
# 3. Click Save
# 4. GitHub creates CNAME file in repo root
----

=== 3.2 Configure DNS Records

==== If using Cloudflare (Recommended)

[source,bash]
----
# 1. Go to Cloudflare Dashboard > DNS
# 2. Add these records:

# A records (GitHub Pages IPs)
axel-protocol.org.  A  185.199.108.153
axel-protocol.org.  A  185.199.109.153
axel-protocol.org.  A  185.199.110.153
axel-protocol.org.  A  185.199.111.153

# AAAA records (IPv6)
axel-protocol.org.  AAAA  2606:50c0:8000::153
axel-protocol.org.  AAAA  2606:50c0:8001::153
axel-protocol.org.  AAAA  2606:50c0:8002::153
axel-protocol.org.  AAAA  2606:50c0:8003::153

# WWW redirect (optional)
www.axel-protocol.org.  CNAME  hyperpolymath.github.io.
----

*Proxy Status*: Set to "DNS only" (gray cloud), not "Proxied" (orange cloud)

*Why*: GitHub Pages HTTPS requires direct connection

==== If using Namecheap or Gandi

[source,bash]
----
# In your DNS management panel, add:

Type: A
Host: @
Value: 185.199.108.153
TTL: 300

# Repeat for other 3 IPs (185.199.109.153, 110, 111)

Type: AAAA
Host: @
Value: 2606:50c0:8000::153
TTL: 300

# Repeat for other 3 IPv6 addresses

Type: CNAME
Host: www
Value: hyperpolymath.github.io.
TTL: 300
----

=== 3.3 Verify DNS Propagation

[source,bash]
----
# Check DNS records
dig axel-protocol.org A +short
# Should return: 185.199.108.153, 109, 110, 111

dig axel-protocol.org AAAA +short
# Should return: 2606:50c0:8000::153, 8001, 8002, 8003

# Test resolution
curl -I https://axel-protocol.org
# Should return: HTTP/2 200 (after DNS propagates)
----

*Note*: DNS propagation takes 5 minutes to 24 hours (usually ~10 minutes)

== Step 4: Enable HTTPS

=== 4.1 Wait for Certificate

After DNS propagates, GitHub automatically provisions a Let's Encrypt certificate:

1. Go to https://github.com/hyperpolymath/axel-protocol/settings/pages
2. Wait for "HTTPS certificate is being created" message
3. Certificate usually ready in 10-30 minutes

=== 4.2 Enforce HTTPS

Once certificate is active:

[source,bash]
----
# Via web UI:
# 1. Go to Settings > Pages
# 2. Check "Enforce HTTPS"
# 3. Click Save
----

*Result*: `http://axel-protocol.org` redirects to `https://axel-protocol.org`

== Step 5: Add www Redirect (Optional)

If you want `www.axel-protocol.org` to redirect to `axel-protocol.org`:

[source,bash]
----
# Already configured in Step 3.2 (CNAME for www)
# Test:
curl -I https://www.axel-protocol.org
# Should redirect to https://axel-protocol.org
----

== Step 6: Test Everything

=== Final Checklist

[source,bash]
----
# 1. Test apex domain
curl -I https://axel-protocol.org
# Expected: HTTP/2 200

# 2. Test www redirect
curl -I https://www.axel-protocol.org
# Expected: HTTP/2 301 → https://axel-protocol.org

# 3. Test IPv6
curl -6 -I https://axel-protocol.org
# Expected: HTTP/2 200

# 4. Verify content
curl -s https://axel-protocol.org | grep -i "AXEL Protocol"
# Expected: Match found in <title> or <h1>
----

=== Expected Results

* ✅ `https://axel-protocol.org` loads `index.html`
* ✅ HTTPS enforced (HTTP → HTTPS redirect)
* ✅ IPv6 works
* ✅ `www.axel-protocol.org` redirects to apex
* ✅ Let's Encrypt certificate valid

== Troubleshooting

=== "Certificate not yet created"

*Symptom*: GitHub Pages shows "Certificate is being created..." for >1 hour

*Solutions*:
1. Verify DNS records are correct (dig axel-protocol.org)
2. Ensure Cloudflare proxy is DISABLED (gray cloud, not orange)
3. Remove and re-add custom domain in GitHub settings
4. Wait 24 hours (Let's Encrypt rate limits)

=== "404 Not Found"

*Symptom*: `axel-protocol.org` returns 404

*Solutions*:
1. Check `CNAME` file exists in repo root (GitHub creates it automatically)
2. Verify `index.html` is in repo root (not in `docs/`)
3. Check GitHub Pages is enabled (Settings > Pages)
4. Wait for deployment (Actions tab shows gh-pages workflow)

=== DNS not resolving

*Symptom*: `dig axel-protocol.org` returns NXDOMAIN

*Solutions*:
1. Wait for DNS propagation (up to 24 hours)
2. Check DNS records in registrar dashboard
3. Flush local DNS cache: `sudo systemd-resolve --flush-caches`

== Maintenance

=== Updating Content

[source,bash]
----
cd ~/Documents/hyperpolymath-repos/axel-protocol

# Edit index.html
vim index.html

# Commit and push (GitHub auto-deploys)
git add index.html
git commit -m "Update website content"
git push origin main

# Site updates in ~1 minute
----

=== Renewing Certificate

GitHub auto-renews Let's Encrypt certificates (90-day validity).

*No action required.*

=== Monitoring Uptime

Use GitHub's status page: https://www.githubstatus.com/

Or add external monitoring:
* UptimeRobot (free)
* Pingdom
* Cloudflare Analytics (if proxied)

== Advanced: Custom 404 Page

Create `404.html` in repo root:

[source,html]
----
<!DOCTYPE html>
<html>
<head><title>404 - AXEL Protocol</title></head>
<body>
  <h1>Page Not Found</h1>
  <p>Return to <a href="/">AXEL Protocol homepage</a></p>
</body>
</html>
----

GitHub serves this for missing pages.

== Support

* *GitHub Pages docs*: https://docs.github.com/en/pages
* *DNS issues*: Check registrar support
* *Certificate issues*: https://letsencrypt.org/docs/

For AXEL-specific questions: info@axel-protocol.org
