fix(health): support HEAD method for health endpoint
This commit is contained in:
398
docs/guides/real-client-testing-cheatsheet.md
Normal file
398
docs/guides/real-client-testing-cheatsheet.md
Normal file
@@ -0,0 +1,398 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
python -c "import secrets; print(secrets.token_urlsafe(32))"
|
||||
```
|
||||
|
||||
### Create .env File
|
||||
|
||||
```bash
|
||||
cd /path/to/gondulf
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env` with minimum required settings:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```html
|
||||
<!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
|
||||
|
||||
```html
|
||||
<!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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
curl -s https://auth.thesatelliteoflove.com/.well-known/oauth-authorization-server | jq .
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
# View live logs
|
||||
podman logs -f gondulf
|
||||
|
||||
# View last 100 lines
|
||||
podman logs --tail 100 gondulf
|
||||
```
|
||||
|
||||
### Enable Debug Mode (Development Only)
|
||||
|
||||
In `.env`:
|
||||
|
||||
```bash
|
||||
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 | grep -i smtp` |
|
||||
| "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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
Block a user