Skip to content

GitHub Pages and DNS

Jump to bottom
Copilot edited this page Jul 11, 2026 · 1 revision

GitHub Pages and DNS

This page documents how the project's own marketing/landing page is hosted and wired up - useful context for future maintainers, and a template if you ever want to do the same for a fork or white-labeled deployment. This is unrelated to the Custom Domain Setup for the deployed API (app.nmailx.com in that example) - that's your /send and /admin endpoints; this page is about the project's static landing page.

What's deployed

  • Source lives in docs/index.html (plus docs/CNAME) on the main branch of the repo - a single, hand-written, dependency-free HTML/CSS page (no CDN, no framework, no build step), consistent with this project's general preference for vendoring or hand-rolling its own frontend assets rather than depending on a CDN (see Vendored Assets).
  • GitHub Pages is configured to deploy from main, folder /docs, using GitHub's built-in "Deploy from a branch" source (not a custom Actions workflow) - the simplest option, since GitHub Pages' branch-deploy source only supports the repo root or a folder literally named /docs (not an arbitrary folder name).
  • docs/CNAME contains www.nmailx.com - GitHub Pages reads this file to configure the custom domain automatically.

Why /docs instead of a top-level site/ folder

GitHub Pages' built-in branch-deploy source can only point at the repo root or a folder named exactly /docs. A custom folder name (e.g. /site) would require switching to an Actions-based deploy (actions/upload-pages-artifact + actions/deploy-pages), which adds a workflow and a build step for no real benefit here, since the page has no build process to begin with. /docs was chosen to keep things simple.

DNS (Cloudflare)

nmailx.com's DNS is managed in Cloudflare, same as the domains this project sends email from. Two records/rules make www.nmailx.com work and send the bare apex to it:

  1. www CNAME -> napalm255.github.io, set to DNS-only (grey cloud), not proxied. This matches the project's existing convention for DNS-only records (see the DKIM and custom-domain CNAMEs in Custom Domain Setup) - a proxied record would interfere with GitHub's automatic TLS certificate issuance and custom domain verification for Pages.
  2. Apex redirect - a Cloudflare Redirect Rule (Rules -> Redirect Rules) that matches requests to the bare nmailx.com hostname and redirects them (301) to the equivalent path on https://www.nmailx.com. This keeps www.nmailx.com as the single canonical hostname rather than trying to serve Pages directly from the apex (GitHub Pages' apex support requires A/AAAA records to GitHub's IPs, which is more fragile to keep in sync than a redirect rule).

Enabling "Enforce HTTPS"

GitHub can only issue/validate the TLS certificate for the custom domain once the CNAME above has propagated and GitHub's own domain verification succeeds. After that, enable "Enforce HTTPS" in the repo's Pages settings (Settings -> Pages) so http://www.nmailx.com redirects to https://.

Verifying it's working

# Pages build/config status
gh api repos/napalm255/nmailx/pages --jq '{html_url, cname, status, https_enforced}'

# Once DNS has propagated
curl -I https://www.nmailx.com     # expect 200 from GitHub Pages
curl -I https://nmailx.com         # expect a redirect to https://www.nmailx.com

Clone this wiki locally