DanConwayDev
28c881ba97
Agents need repeatable provider inputs instead of translating a generic container guide into mutable dashboard settings on every deployment. Add Railway, Render, and Fly.io configurations that all build the canonical Dockerfile, mount /data, expose one HTTP service, allow bounded shutdown, and avoid overlapping writers. Pair them with provider-specific CLI and dashboard instructions, DNS verification, backup cautions, and one-instance constraints. The templates assume each provider terminates TLS and preserves WebSocket upgrades. Render still requires a supported connected Git source for Blueprint automation, and provider credentials or account mutations are deliberately outside this commit. Validated Railway and Render against their current published JSON schemas, parsed both TOML files and all YAML, checked Fly fields against its current official reference, verified local documentation links, and ran git diff --check. flyctl strict validation was not possible without a Fly access token.
How-To Guides
Task-oriented documentation - Practical solutions to common problems.
What Are How-To Guides?
How-to guides are recipes that show you how to solve specific problems or accomplish particular tasks.
Characteristics:
- ✅ Task-oriented (solve a problem)
- ✅ Practical (actionable steps)
- ✅ Assume basic knowledge
- ✅ Focus on results
- ✅ Can be followed in any order
Not how-to guides:
- ❌ Complete lessons for beginners (those are Tutorials)
- ❌ Technical specifications (those are Reference)
- ❌ Conceptual discussions (those are Explanation)
Available How-To Guides
Upgrade from v2 to v3 Git family storage
Problem: Perform the one-way identifier-family storage migration safely Difficulty: Advanced
You'll learn:
- Prepare capacity and a snapshot-based rollback point
- Run the automatic crash-safe v3 launch migration
- Interpret migration and integrity summary logs
- Restore v2 safely when a release rollback is required
Configure Nix Flakes
Problem: Set up reproducible development environment
Difficulty: Intermediate
You'll learn:
- Enable Nix flakes
- Enter development environment
- Work with subprojects
- Troubleshoot common issues
Test Sync Against Production Data
Problem: Debug and improve sync using real-world data
Difficulty: Intermediate
You'll learn:
- Run sync against production relays
- Sanitize logs for LLM analysis
- Identify common issues and patterns
- Iteratively improve sync behavior
Planned How-To Guides
Deploy ngit-grasp
Status: 🔜 Planned (waiting for main server)
Problem: Deploy to production
You'll learn:
- Server requirements
- Reverse proxy setup (nginx/Caddy)
- SSL/TLS configuration
- Monitoring and logging
Run Compliance Tests
Status: 🔜 Planned
Problem: Test GRASP compliance
You'll learn:
- Set up test relay
- Run integration tests
- Interpret results
- Add custom tests
Upgrade nostr-sdk
Status: 🔜 Planned
Problem: Handle breaking changes in nostr-sdk
You'll learn:
- Check for breaking changes
- Update dependencies
- Fix compilation errors
- Test after upgrade
Configure Authentication
Status: 🔜 Planned (feature not yet implemented)
Problem: Secure your relay
You'll learn:
- Enable authentication
- Configure allowed users
- Set up rate limiting
- Monitor access
Backup and Restore
Status: 🔜 Planned
Problem: Protect your data
You'll learn:
- Backup Git repositories
- Backup Nostr events
- Restore from backup
- Automate backups
How to Use How-To Guides
- Find your problem - Browse or search for what you need
- Check prerequisites - Make sure you have required knowledge
- Follow the steps - Adapt to your specific situation
- Solve and move on - No need to read everything
Not sure if this is what you need?
- New to ngit-grasp? → Tutorials
- Looking for technical details? → Reference
- Want to understand why? → Explanation
Contributing How-To Guides
When writing a how-to guide:
DO:
- ✅ Start with the problem/goal
- ✅ List prerequisites clearly
- ✅ Provide concrete steps
- ✅ Include troubleshooting
- ✅ Show examples
- ✅ Link to related docs
DON'T:
- ❌ Teach basics (link to Tutorials)
- ❌ Explain every concept (link to Explanation)
- ❌ List all options (link to Reference)
- ❌ Make it a tutorial (stay focused on the task)
Template:
# How-To: [Task/Problem]
**Problem:** [What you're trying to accomplish]
**Difficulty:** [Beginner/Intermediate/Advanced]
**Time:** [Estimated time]
## Prerequisites
- [Required knowledge/tools]
## Solution
### Step 1: [Action]
[Instructions]
### Step 2: [Action]
[Instructions]
## Troubleshooting
### [Common problem]
**Solution:** [How to fix]
## Related Documentation
- [Links to relevant docs]
See Diátaxis: How-To Guides for detailed guidance.
Part of the ngit-grasp documentation using the Diátaxis framework.