mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 15:08:24 +00:00
DanConwayDev
22bbd48537
The production guide was NixOS-only despite presenting itself as the general deployment entry point, and its examples referenced an unavailable GitHub source and a hardening control the module does not set. Turn the entry point into an environment chooser, preserve the corrected NixOS material in its own guide, add a hardened generic systemd unit and repeatable Linux installation, document the preferred unprivileged Proxmox layout, and update repository navigation and architecture references. Each path assumes the shared deployment contract from the container change. Kubernetes automation, remote host mutation, and changes to the existing NixOS module are deliberately excluded. Validated the canonical Git remote with git ls-remote, parsed and scored the systemd unit with systemd-analyze, checked all new deployment-guide links, removed trailing whitespace, scanned the staged diff for key-shaped nsec values, and ran git diff --check.
192 lines
4.3 KiB
Markdown
192 lines
4.3 KiB
Markdown
# 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
|
|
|
|
### [Deploy ngit-grasp](deploy.md)
|
|
|
|
**Problem:** Run a durable production relay in a supported hosting environment
|
|
|
|
**You'll learn:**
|
|
|
|
- Choose Docker, NixOS, systemd Linux, Proxmox, or managed hosting
|
|
- Preserve the relay identity, Git repositories, and LMDB state
|
|
- Configure TLS, verify protocols, back up, and upgrade safely
|
|
|
|
---
|
|
|
|
### [Upgrade from v2 to v3 Git family storage](upgrade-git-family-storage.md)
|
|
|
|
**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](nix-flakes.md)
|
|
**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](production-sync-testing.md)
|
|
**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
|
|
|
|
### 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
|
|
|
|
1. **Find your problem** - Browse or search for what you need
|
|
2. **Check prerequisites** - Make sure you have required knowledge
|
|
3. **Follow the steps** - Adapt to your specific situation
|
|
4. **Solve and move on** - No need to read everything
|
|
|
|
**Not sure if this is what you need?**
|
|
- New to ngit-grasp? → [Tutorials](../tutorials/)
|
|
- Looking for technical details? → [Reference](../reference/)
|
|
- Want to understand why? → [Explanation](../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:**
|
|
```markdown
|
|
# 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](https://diataxis.fr/how-to-guides/) for detailed guidance.
|
|
|
|
---
|
|
|
|
*Part of the [ngit-grasp documentation](../README.md) using the [Diátaxis](https://diataxis.fr/) framework.*
|