Self managed NIP‐05 via GitHub Pages with Custom Domain - avren-gn8/home GitHub Wiki

✅ Requirements

  • GitHub account
  • Own domain (e.g., yourdomain.com)
  • Public Nostr key in hex format (not npub!)
  • Basic DNS configuration knowledge

🛒 1. Register a Domain

Register a domain from a provider like orangewebsite, njal.la, or similar.

🌐 2. Configure DNS Records for GitHub Pages

Set the following A records for your domain (via your DNS provider):

Type Host Value TTL Priority
A @ (or blank) 185.199.108.153 300
A @ (or blank) 185.199.109.153 300
A @ (or blank) 185.199.110.153 300
A @ (or blank) 185.199.111.153 300

Optional:
Add a CNAME record for www → yourusername.github.io

📁 3. Create a GitHub Repository

  1. Go to https://github.com/new
  2. Repository name: e.g., nip5
  3. Check "Add a README"
  4. Click "Create repository"

🏗️ 4. Create Directory & File

a) .well-known/nostr.json

Path: .well-known/nostr.json

Put you nostrhandle (nostrname) and your nostr public key in the file. Example content:

{
  "names": {
    "petermuster": "ldajflasjföldsjflj..."
  }
}

IMPORTANT: Use your hex-encoded Nostr public key, not the npub1... format.

b) _config.yml in Root

Create a file named _config.yml with this content:

include: [".well-known"]

This ensures GitHub includes the .well-known folder in the build output.

⚙️ 5. Configure GitHub Pages

  1. Go to Settings > Pages inside your repository
  2. Under "Build and Deployment":
    • Choose: Deploy from branch
    • Branch: main or master
  3. Under Custom domain:
    • Enter yourdomain.com
    • Ignore any warning
  4. Enable ✅ Enforce HTTPS

It may take a few minutes for the certificate to be issued.

image

🔍 6. Configure Nostr Client

Open your Nostr client and set the NIP-05 identifier as:

[email protected]  e.g. [email protected]

Save – done!

✅ Test

In your browser or via curl:

curl https://yourdomain.com/.well-known/nostr.json?name=petermuster

Expected output:

{
  "names": {
    "Nostr Benutzer": "elkajdlkajslfkjaödlkfjs..."
  }
}

🛡️ Privacy Tips

Item Recommendation
Public key is visible Use pseudonyms only
Register a KYC-free domain e.g., orangewebsite, njal.la
Use KYC-free email for GitHub e.g., ProtonMail
GitHub repository visibility Must be public for GitHub Pages
Commit metadata Use a separate pseudonymous user
Avoid tracking Don’t include analytics scripts