mirror of
https://relay.ngit.dev/npub15qydau2hjma6ngxkl2cyar74wzyjshvl65za5k5rl69264ar2exs5cyejr/ngit-grasp.git
synced 2026-10-05 23:18: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.
171 lines
6.4 KiB
Markdown
171 lines
6.4 KiB
Markdown
# ngit-grasp Documentation
|
|
|
|
Welcome to the **ngit-grasp** documentation! We use the [Diátaxis](https://diataxis.fr/) framework to organize our documentation into four types, each serving a different purpose.
|
|
|
|
```
|
|
PRACTICAL THEORETICAL
|
|
───────── ───────────
|
|
|
|
LEARNING │ Tutorials │ Explanation │
|
|
│ │ │
|
|
│ Getting │ Architecture │
|
|
│ Started │ Decisions │
|
|
│ │ │
|
|
├────────────────┼──────────────────┤
|
|
│ │ │
|
|
WORKING │ How-To │ Reference │
|
|
│ Guides │ │
|
|
│ │ API Docs │
|
|
│ Deployment │ Protocols │
|
|
│ Testing │ │
|
|
│ │ │
|
|
```
|
|
|
|
## 📚 Documentation Types
|
|
|
|
### 🎓 [Tutorials](tutorials/) - *Learning by Doing*
|
|
**Purpose:** Learn the basics through practical steps
|
|
**For:** Newcomers getting started
|
|
**Style:** Step-by-step lessons with guaranteed outcomes
|
|
|
|
- **[Getting Started](tutorials/getting-started.md)** - Your first ngit-grasp setup
|
|
- **[Running Your First Audit](tutorials/first-audit.md)** - Using grasp-audit tool
|
|
|
|
### 🔧 [How-To Guides](how-to/) - *Solving Problems*
|
|
**Purpose:** Accomplish specific tasks
|
|
**For:** Users with basic knowledge solving real problems
|
|
**Style:** Practical recipes and solutions
|
|
|
|
- **[Deploy ngit-grasp](how-to/deploy.md)** - Choose Docker, NixOS, Linux, Proxmox, or managed hosting
|
|
- **[Deployment contract](reference/deployment-contract.md)** - Shared runtime and persistence requirements
|
|
- **[Configure Nix Flakes](how-to/nix-flakes.md)** - Nix development environment
|
|
- **[Run Compliance Tests](how-to/test-compliance.md)** - GRASP compliance testing
|
|
- **[Upgrade nostr-sdk](how-to/upgrade-nostr-sdk.md)** - Handling SDK upgrades
|
|
|
|
### 📖 [Reference](reference/) - *Technical Information*
|
|
**Purpose:** Look up technical details
|
|
**For:** Users who know what they're looking for
|
|
**Style:** Dry, factual, comprehensive
|
|
|
|
- **[Git Protocol](reference/git-protocol.md)** - Git Smart HTTP protocol details
|
|
- **[GRASP Protocol](reference/grasp-protocol.md)** - GRASP specification details
|
|
- **[Configuration](reference/configuration.md)** - All config options
|
|
- **[API Reference](reference/api.md)** - Internal API documentation
|
|
|
|
### 💡 [Explanation](explanation/) - *Understanding Concepts*
|
|
**Purpose:** Understand the "why" and design decisions
|
|
**For:** Users wanting deeper understanding
|
|
**Style:** Discussion, context, alternatives
|
|
|
|
- **[Architecture Overview](explanation/architecture.md)** - System design and components
|
|
- **[Inline Authorization](explanation/inline-authorization.md)** - Why we chose this approach
|
|
- **[Administration Vision](explanation/administration-vision.md)** -
|
|
Nostr-authenticated management, embedded UI, and runtime configuration
|
|
- **[Comparison with ngit-relay](explanation/comparison.md)** - How we differ from reference
|
|
- **[Design Decisions](explanation/decisions.md)** - Key architectural choices
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start Paths
|
|
|
|
### I'm brand new to ngit-grasp
|
|
1. Read [README.md](../README.md) for project overview
|
|
2. Follow [Getting Started Tutorial](tutorials/getting-started.md)
|
|
3. Understand [Architecture Overview](explanation/architecture.md)
|
|
|
|
### I want to deploy ngit-grasp
|
|
1. Review [Configuration Reference](reference/configuration.md)
|
|
2. Choose an environment in [Deploy ngit-grasp](how-to/deploy.md)
|
|
3. Verify the deployment and test its backup
|
|
|
|
### I want to develop on ngit-grasp
|
|
1. Follow [Getting Started Tutorial](tutorials/getting-started.md)
|
|
2. Read [Architecture Overview](explanation/architecture.md)
|
|
3. Check [Nix Flakes How-To](how-to/nix-flakes.md)
|
|
4. Review [Test Strategy](how-to/test-compliance.md)
|
|
|
|
### I want to understand the design
|
|
1. Read [Inline Authorization Explanation](explanation/inline-authorization.md)
|
|
2. Review [Design Decisions](explanation/decisions.md)
|
|
3. Compare with [ngit-relay Comparison](explanation/comparison.md)
|
|
|
|
### I'm looking for specific information
|
|
- **Protocol details?** → [Reference](reference/)
|
|
- **Configuration options?** → [Configuration Reference](reference/configuration.md)
|
|
- **Git protocol?** → [Git Protocol Reference](reference/git-protocol.md)
|
|
|
|
---
|
|
|
|
## 📂 Additional Resources
|
|
|
|
### [Archive](archive/)
|
|
Historical session notes and completed work. Useful for understanding project evolution but not required reading.
|
|
|
|
### [Learnings](learnings/)
|
|
**DEPRECATED** - Being migrated to Diátaxis structure:
|
|
- Gotchas → How-To Guides
|
|
- Patterns → Reference or Explanation
|
|
- Notes → Appropriate category
|
|
|
|
---
|
|
|
|
## 🤝 Contributing to Documentation
|
|
|
|
When adding documentation, ask yourself:
|
|
|
|
**Is it a tutorial?**
|
|
- Does it teach a beginner?
|
|
- Is it a complete lesson with guaranteed outcome?
|
|
- → Add to `tutorials/`
|
|
|
|
**Is it a how-to guide?**
|
|
- Does it solve a specific problem?
|
|
- Is it a recipe for accomplishing a task?
|
|
- → Add to `how-to/`
|
|
|
|
**Is it reference material?**
|
|
- Is it technical information?
|
|
- Will people look it up when needed?
|
|
- → Add to `reference/`
|
|
|
|
**Is it explanation?**
|
|
- Does it explain "why"?
|
|
- Does it discuss alternatives or design?
|
|
- → Add to `explanation/`
|
|
|
|
See [Diátaxis documentation](https://diataxis.fr/) for more guidance.
|
|
|
|
---
|
|
|
|
## 📊 Project Status
|
|
|
|
**ALPHA** - Under active development. Core functionality working, API may change.
|
|
|
|
### Completed
|
|
- ✅ grasp-audit compliance testing tool
|
|
- ✅ Nix flake development environment
|
|
- ✅ nostr-sdk 0.43 upgrade
|
|
- ✅ Documentation restructure (Diátaxis)
|
|
|
|
### In Progress
|
|
- 🔄 Core ngit-grasp server implementation
|
|
- 🔄 GRASP-01 compliance
|
|
|
|
### Planned
|
|
- 🔜 GRASP-02 (Proactive Sync)
|
|
- 🔜 GRASP-05 (Archive)
|
|
|
|
---
|
|
|
|
## 🔗 External Links
|
|
|
|
- [GRASP Protocol Specification](https://gitworkshop.dev/danconwaydev.com/grasp)
|
|
- [NIP-34 (Git Stuff)](https://nips.nostr.com/34)
|
|
- [Diátaxis Framework](https://diataxis.fr/)
|
|
- [rust-nostr Documentation](https://docs.rs/nostr-sdk/)
|
|
|
|
---
|
|
|
|
*Documentation structure based on [Diátaxis](https://diataxis.fr/)*
|
|
*Last updated: November 4, 2025*
|