phil/Gondulf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Gondulf/docs/guides/real-client-testing-cheatsheet.md

10 KiB
Raw Permalink Blame History

Real Client Testing Cheat Sheet

Quick guide to test Gondulf with real IndieAuth clients. Target: working auth in 15-30 minutes.

1. Quick Start Setup

Generate Secret Key

python -c "import secrets; print(secrets.token_urlsafe(32))"

Create .env File

cd /path/to/gondulf
cp .env.example .env

Edit .env with minimum required settings:

# Required - paste your generated key
GONDULF_SECRET_KEY=your-generated-secret-key-here

# Your auth server URL (use your actual domain)
GONDULF_BASE_URL=https://auth.thesatelliteoflove.com

# Database (container path)
GONDULF_DATABASE_URL=sqlite:////data/gondulf.db

# SMTP - use your provider (example: Gmail)
GONDULF_SMTP_HOST=smtp.gmail.com
GONDULF_SMTP_PORT=587
GONDULF_SMTP_USERNAME=your-email@gmail.com
GONDULF_SMTP_PASSWORD=your-app-specific-password
GONDULF_SMTP_FROM=your-email@gmail.com
GONDULF_SMTP_USE_TLS=true

# Production settings
GONDULF_HTTPS_REDIRECT=true
GONDULF_TRUST_PROXY=true
GONDULF_SECURE_COOKIES=true
GONDULF_DEBUG=false

Run with Podman/Docker

# Build
podman build -t gondulf:latest -f Containerfile .

# Run (creates volume for persistence)
podman run -d \
  --name gondulf \
  -p 8000:8000 \
  -v gondulf_data:/data \
  --env-file .env \
  gondulf:latest

# Or with docker-compose/podman-compose
podman-compose up -d

Verify Server Running

curl https://auth.thesatelliteoflove.com/health
# Expected: {"status":"healthy","database":"connected"}

curl https://auth.thesatelliteoflove.com/.well-known/oauth-authorization-server
# Expected: JSON with authorization_endpoint, token_endpoint, etc.

2. Domain Setup

DNS TXT Record

Add this TXT record to your domain DNS:

Type Host Value
TXT @ (or thesatelliteoflove.com) gondulf-verify-domain

Verify with:

dig TXT thesatelliteoflove.com +short
# Expected: "gondulf-verify-domain"

Note: DNS propagation can take up to 48 hours, but usually completes within minutes.

Homepage rel="me" Link

Add a rel="me" link to your homepage pointing to your email:

<!DOCTYPE html>
<html>
<head>
  <title>Your Homepage</title>
  <!-- rel="me" link in head -->
  <link rel="me" href="mailto:you@thesatelliteoflove.com">
</head>
<body>
  <h1>thesatelliteoflove.com</h1>

  <!-- Or as a visible link in body -->
  <a rel="me" href="mailto:you@thesatelliteoflove.com">Email me</a>
</body>
</html>

Important: The email domain should match your website domain OR be an email you control (Gondulf sends a verification code to this address).

Complete Homepage Example

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>thesatelliteoflove.com</title>
  <link rel="me" href="mailto:phil@thesatelliteoflove.com">
  <link rel="authorization_endpoint" href="https://auth.thesatelliteoflove.com/authorize">
  <link rel="token_endpoint" href="https://auth.thesatelliteoflove.com/token">
</head>
<body>
  <div class="h-card">
    <h1 class="p-name">Phil</h1>
    <p><a class="u-url" rel="me" href="https://thesatelliteoflove.com/">thesatelliteoflove.com</a></p>
    <p><a rel="me" href="mailto:phil@thesatelliteoflove.com">phil@thesatelliteoflove.com</a></p>
  </div>
</body>
</html>

3. Testing with Real Clients

Important: These are IndieAuth CLIENTS that will authenticate against YOUR Gondulf server. Your domain needs to point its authorization and token endpoints to Gondulf, not to IndieLogin.

Note about IndieLogin.com: IndieLogin.com is NOT a client - it's an IndieAuth provider/server like Gondulf. Gondulf is designed to REPLACE IndieLogin as your authentication provider. If your domain points to IndieLogin's endpoints, you're using IndieLogin for auth, not Gondulf.

Option A: IndieWeb Wiki (Easiest Test)

The IndieWeb wiki uses IndieAuth for login.

  1. Go to: https://indieweb.org/
  2. Click "Log in" (top right)
  3. Enter your domain: https://thesatelliteoflove.com/
  4. Click "Log In"

Expected flow:

  • Wiki discovers your authorization endpoint (Gondulf)
  • Redirects to your Gondulf server
  • Gondulf verifies DNS TXT record
  • Gondulf discovers your email from rel="me"
  • Sends verification code to your email
  • You enter the code
  • Consent screen appears
  • Approve authorization
  • Redirected back to IndieWeb wiki as logged in

Option B: Quill (Micropub Posting Client)

Quill is a web-based Micropub client for creating posts.

  1. Go to: https://quill.p3k.io/
  2. Enter your domain: https://thesatelliteoflove.com/
  3. Click "Sign In"

Note: Quill will attempt to discover your Micropub endpoint after auth. For testing auth only, you can ignore Micropub errors after successful authentication.

Option C: Monocle (Feed Reader)

Monocle is a web-based social feed reader.

  1. Go to: https://monocle.p3k.io/
  2. Enter your domain: https://thesatelliteoflove.com/
  3. Sign in

Note: Monocle will look for a Microsub endpoint after auth. The authentication itself will still work without one.

Option D: Teacup (Check-in App)

Teacup is for food/drink check-ins.

  1. Go to: https://teacup.p3k.io/
  2. Enter your domain to sign in

Option E: Micropublish (Simple Posting)

Micropublish is a simple web interface for creating posts.

  1. Go to: https://micropublish.net/
  2. Enter your domain to authenticate

Option F: Indigenous (Mobile Apps)

Indigenous has apps for iOS and Android that support IndieAuth.

  • iOS: Search "Indigenous" in App Store
  • Android: Search "Indigenous" in Play Store
  • Configure with your domain: https://thesatelliteoflove.com/

Option G: Omnibear (Browser Extension)

Omnibear is a browser extension for Firefox and Chrome.

  1. Install from browser extension store
  2. Configure with your domain
  3. Use to sign in and post from any webpage

Option H: Custom Test Client (curl)

Test the authorization endpoint directly:

# Generate PKCE verifier and challenge
CODE_VERIFIER=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')

echo "Verifier: $CODE_VERIFIER"
echo "Challenge: $CODE_CHALLENGE"

# Open this URL in browser:
echo "https://auth.thesatelliteoflove.com/authorize?\
client_id=https://example.com/&\
redirect_uri=https://example.com/callback&\
response_type=code&\
state=test123&\
code_challenge=$CODE_CHALLENGE&\
code_challenge_method=S256&\
me=https://thesatelliteoflove.com/"

4. Verification Checklist

DNS Verification

# Check TXT record exists
dig TXT thesatelliteoflove.com +short
# Must return: "gondulf-verify-domain"

# Alternative: query specific DNS server
dig @8.8.8.8 TXT thesatelliteoflove.com +short

Email Discovery Verification

# Check your homepage serves rel="me" email link
curl -s https://thesatelliteoflove.com/ | grep -i 'rel="me"'
# Must show: href="mailto:your@email.com"

# Or check with a parser
curl -s https://thesatelliteoflove.com/ | grep -oP 'rel="me"[^>]*href="mailto:[^"]+"'

Server Metadata Verification

curl -s https://auth.thesatelliteoflove.com/.well-known/oauth-authorization-server | jq .

Expected output:

{
  "issuer": "https://auth.thesatelliteoflove.com",
  "authorization_endpoint": "https://auth.thesatelliteoflove.com/authorize",
  "token_endpoint": "https://auth.thesatelliteoflove.com/token",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": [],
  "token_endpoint_auth_methods_supported": ["none"],
  "revocation_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": []
}

Complete Flow Test

  1. DNS check passes (TXT record found)
  2. Email discovered (rel="me" link found)
  3. Verification email received
  4. Code entered successfully
  5. Consent screen displayed
  6. Authorization code returned
  7. Token exchanged successfully
  8. Client shows logged in as https://thesatelliteoflove.com/

5. Troubleshooting

Check Server Logs

# View live logs
podman logs -f gondulf

# View last 100 lines
podman logs --tail 100 gondulf

Enable Debug Mode (Development Only)

In .env:

GONDULF_DEBUG=true
GONDULF_LOG_LEVEL=DEBUG
GONDULF_HTTPS_REDIRECT=false

Warning: Never use DEBUG=true in production.

Common Issues

Problem Solution
"dns_verification_failed" Add TXT record: gondulf-verify-domain. Wait for DNS propagation (check with dig).
"email_discovery_failed" Add <link rel="me" href="mailto:you@domain.com"> to your homepage.
"email_send_failed" Check SMTP settings. Test with: `podman logs gondulf
"Invalid me URL" Ensure me parameter uses HTTPS and is a valid URL
"client_id must use HTTPS" Client applications must use HTTPS URLs
"redirect_uri does not match" redirect_uri domain must match client_id domain
Health check fails Check database volume permissions: podman exec gondulf ls -la /data
Container won't start Check for missing env vars: podman logs gondulf

SMTP Testing

Test email delivery independently:

# Check SMTP connection (Python)
python -c "
import smtplib
with smtplib.SMTP('smtp.gmail.com', 587) as s:
    s.starttls()
    s.login('your-email@gmail.com', 'app-password')
    print('SMTP connection successful')
"

DNS Propagation Check

# Check multiple DNS servers
for ns in 8.8.8.8 1.1.1.1 9.9.9.9; do
  echo "Checking $ns:"
  dig @$ns TXT thesatelliteoflove.com +short
done

Database Issues

# Check database exists and is writable
podman exec gondulf ls -la /data/

# Check database schema
podman exec gondulf sqlite3 /data/gondulf.db ".tables"

Quick Reference

Endpoint URL
Health GET /health
Metadata GET /.well-known/oauth-authorization-server
Authorization GET /authorize
Token POST /token
Start Verification POST /api/verify/start
Verify Code POST /api/verify/code
Required DNS Record Value
TXT @ gondulf-verify-domain
Required HTML Example
rel="me" email <link rel="me" href="mailto:you@example.com">
authorization_endpoint <link rel="authorization_endpoint" href="https://auth.example.com/authorize">
token_endpoint <link rel="token_endpoint" href="https://auth.example.com/token">
Reference in New Issue View Git Blame Copy Permalink