blob: 1a569852b7e5f0ff7a67cd2656e9a83f854351e6 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
# Tutorial: Getting Started with ngit-grasp
**Purpose:** Learn the basics of ngit-grasp through hands-on setup
**Time:** 15-20 minutes
**Prerequisites:** Basic Git and command-line knowledge
---
## What You'll Learn
By the end of this tutorial, you will:
- ✅ Have a working ngit-grasp development environment
- ✅ Understand the basic project structure
- ✅ Run the test suite successfully
- ✅ Know where to go next
---
## Step 1: Clone the Repository
First, get the source code:
```bash
git clone https://gitworkshop.dev/ngit-grasp
cd ngit-grasp
```
**What just happened?** You cloned the ngit-grasp repository from the GRASP-enabled Git server.
---
## Step 2: Set Up Nix Development Environment
ngit-grasp uses Nix flakes for reproducible development environments.
```bash
# Enter the development environment
nix develop
# You should see a new shell with all dependencies available
```
**What just happened?** Nix read `flake.nix` and created a shell with:
- Rust toolchain (cargo, rustc)
- Git
- All required system libraries
**Tip:** If `nix develop` doesn't work, you might be using an old Nix version. See the [Nix Flakes How-To](../how-to/nix-flakes.md) for help.
---
## Step 3: Explore the Project Structure
Take a look around:
```bash
# View the project structure
ls -la
# Key directories:
# - src/ - Main ngit-grasp source code (coming soon)
# - grasp-audit/ - Compliance testing tool (working)
# - docs/ - Documentation (you are here!)
```
**What you're seeing:**
- `grasp-audit/` is a **subproject** with its own Cargo workspace
- Main ngit-grasp server implementation is planned but not yet started
- Documentation uses Diátaxis framework (tutorials, how-to, reference, explanation)
---
## Step 4: Work with grasp-audit
The compliance testing tool is the first working component. Let's try it:
```bash
# Navigate to grasp-audit
cd grasp-audit
# Enter its development environment
nix develop
# Build the project
cargo build
# Run unit tests
cargo test
```
**What just happened?**
- `grasp-audit` has its own `flake.nix` for isolated dependencies
- Unit tests run without external dependencies
- Integration tests (marked `#[ignore]`) require a Nostr relay
---
## Step 5: Run Your First Audit (Optional)
If you want to try the audit tool against a real relay:
```bash
# In a separate terminal, start a test relay:
docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
# Back in grasp-audit directory:
cargo test --ignored -- --test-threads=1
```
**What just happened?** Integration tests connected to the relay on port 7000 and verified GRASP compliance.
**Note:** This step is optional. The relay must be running for these tests to pass.
---
## Step 6: Explore the Code
Let's look at a simple example:
```bash
# From grasp-audit directory
cat examples/simple_audit.rs
```
This shows how to use the `grasp-audit` library to check GRASP compliance.
---
## Step 7: Read the Documentation
Now that you have a working setup, explore the documentation:
```bash
# From project root
cd ..
ls docs/
```
**Recommended reading order:**
1. [Architecture Overview](../explanation/architecture.md) - Understand the design
2. [Inline Authorization](../explanation/inline-authorization.md) - Key decision
3. [Git Protocol Reference](../reference/git-protocol.md) - Technical details
---
## What You've Accomplished
Congratulations! You now have:
✅ A working Nix development environment
✅ Built and tested the grasp-audit tool
✅ Understanding of the project structure
✅ Knowledge of where to find more information
---
## Next Steps
### If you want to contribute:
1. Read [Architecture Overview](../explanation/architecture.md)
2. Check open issues on the repository
3. Review [Design Decisions](../explanation/decisions.md)
### If you want to deploy:
1. Follow [Deployment How-To](../how-to/deploy.md)
2. Review [Configuration Reference](../reference/configuration.md)
### If you want to understand GRASP:
1. Read [GRASP Protocol Reference](../reference/grasp-protocol.md)
2. Review [Comparison with ngit-relay](../explanation/comparison.md)
### If you want to run compliance tests:
1. Follow [Running Your First Audit Tutorial](first-audit.md)
2. Review [Compliance Testing How-To](../how-to/test-compliance.md)
---
## Troubleshooting
### "nix develop" doesn't work
- You might need Nix with flakes enabled
- See [Nix Flakes How-To](../how-to/nix-flakes.md)
### Build errors in grasp-audit
- Make sure you're in the `grasp-audit` directory
- Run `nix develop` first
- Check that you have network access (Cargo needs to download crates)
### Tests fail
- Unit tests should always pass
- Integration tests (`--ignored`) require a relay on port 7000
- Use `--test-threads=1` for integration tests
---
## Summary
You've successfully set up ngit-grasp and learned:
- How to use Nix flakes for development
- The project structure (main server + grasp-audit tool)
- How to build and test the code
- Where to find documentation
**Ready for more?** Try the [First Audit Tutorial](first-audit.md) next!
---
*Part of the [ngit-grasp tutorials](./)*
*Next: [Running Your First Audit](first-audit.md)*
|