276 lines
7.2 KiB
Markdown
276 lines
7.2 KiB
Markdown
# ActivityPub Testing Guide
|
|
|
|
Complete guide for testing ActivityPub federation in Solar Network.
|
|
|
|
## 📚 Documentation Files
|
|
|
|
| File | Description | Size |
|
|
|------|-------------|-------|
|
|
| `ACTIVITYPUB_TESTING_INDEX.md` | **START HERE** - Master guide with overview | 12K |
|
|
| `ACTIVITYPUB_TESTING_QUICKSTART.md` | Quick reference for common tasks | 7K |
|
|
| `ACTIVITYPUB_TESTING_GUIDE.md` | Comprehensive testing scenarios (10 parts) | 19K |
|
|
| `ACTIVITYPUB_TESTING_QUICKREF.md` | Command and query reference | 8K |
|
|
| `ACTIVITYPUB_TESTING_HELPER_API.md` | Helper API for programmatic testing | 12K |
|
|
| `ACTIVITYPUB_TESTING_RESULTS_TEMPLATE.md` | Template to track test results | 10K |
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Option A: One-Command Setup (Recommended)
|
|
|
|
```bash
|
|
# 1. Run setup script
|
|
./setup-activitypub-test.sh
|
|
|
|
# 2. Run validation
|
|
./test-activitypub.sh
|
|
|
|
# 3. Start Solar Network
|
|
cd DysonNetwork.Sphere
|
|
dotnet run
|
|
```
|
|
|
|
### Option B: Manual Setup
|
|
|
|
1. **Read**: `ACTIVITYPUB_TESTING_QUICKSTART.md`
|
|
2. **Configure**: Copy `.env.testing.example` to `.env` and adjust
|
|
3. **Follow**: Step-by-step in `ACTIVITYPUB_TESTING_GUIDE.md`
|
|
|
|
## 🎯 What You Can Test
|
|
|
|
### With Self-Hosted Instance
|
|
- ✅ WebFinger discovery
|
|
- ✅ Actor profile retrieval
|
|
- ✅ Follow relationships (bidirectional)
|
|
- ✅ Post federation (Solar → Mastodon)
|
|
- ✅ Content reception (Mastodon → Solar)
|
|
- ✅ Like interactions
|
|
- ✅ Reply threading
|
|
- ✅ HTTP signature verification
|
|
- ✅ Content deletion
|
|
|
|
### With Real Instance
|
|
- ✅ Public domain setup (via ngrok or VPS)
|
|
- ✅ Federation with public instances (mastodon.social, etc.)
|
|
- ✅ Real-world compatibility testing
|
|
- ✅ Performance under real load
|
|
|
|
## 📋 Testing Workflow
|
|
|
|
### Day 1: Basic Functionality
|
|
- Setup test environment
|
|
- Test WebFinger and Actor endpoints
|
|
- Verify HTTP signatures
|
|
- Test basic follow/unfollow
|
|
|
|
### Day 2: Content Federation
|
|
- Test post creation and delivery
|
|
- Test content reception
|
|
- Test media attachments
|
|
- Test content warnings
|
|
|
|
### Day 3: Interactions
|
|
- Test likes (both directions)
|
|
- Test replies and threading
|
|
- Test boosts/announces
|
|
- Test undo activities
|
|
|
|
### Day 4: Real Instance
|
|
- Set up public domain
|
|
- Test with mastodon.social
|
|
- Test with other instances
|
|
- Verify cross-instance compatibility
|
|
|
|
### Day 5: Edge Cases
|
|
- Test error handling
|
|
- Test failed deliveries
|
|
- Test invalid signatures
|
|
- Test malformed activities
|
|
|
|
## 🛠️ Setup Scripts
|
|
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| `setup-activitypub-test.sh` | One-command setup of Mastodon + Solar Network |
|
|
| `test-activitypub.sh` | Quick validation of core functionality |
|
|
|
|
Both scripts are executable (`chmod +x`).
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Required Tools
|
|
- ✅ Docker (for Mastodon)
|
|
- ✅ .NET 10 SDK (for Solar Network)
|
|
- ✅ PostgreSQL client (psql)
|
|
- ✅ curl (for API testing)
|
|
|
|
### Quick Setup
|
|
```bash
|
|
# 1. Install dependencies (Ubuntu/Debian)
|
|
sudo apt-get install docker.io docker-compose postgresql-client curl jq
|
|
|
|
# 2. Run setup
|
|
./setup-activitypub-test.sh
|
|
|
|
# 3. Validate
|
|
./test-activitypub.sh
|
|
```
|
|
|
|
## 📊 Progress Tracking
|
|
|
|
Use the template to track your testing progress:
|
|
|
|
```bash
|
|
# Copy the template
|
|
cp ACTIVITYPUB_TESTING_RESULTS_TEMPLATE.md my-test-results.md
|
|
|
|
# Edit as you test
|
|
nano my-test-results.md
|
|
```
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Quick Fixes
|
|
|
|
**Mastodon won't start**:
|
|
```bash
|
|
# Check logs
|
|
docker compose -f docker-compose.mastodon-test.yml logs -f
|
|
|
|
# Restart containers
|
|
docker compose -f docker-compose.mastodon-test.yml restart
|
|
```
|
|
|
|
**Can't reach Solar Network**:
|
|
```bash
|
|
# Check if running
|
|
curl http://solar.local:5000
|
|
|
|
# Check /etc/hosts
|
|
cat /etc/hosts | grep solar.local
|
|
```
|
|
|
|
**Activities not arriving**:
|
|
```bash
|
|
# Check database
|
|
psql -d dyson_network -c "SELECT * FROM fediverse_activities;"
|
|
|
|
# Check logs
|
|
dotnet run --project DysonNetwork.Sphere | grep -i activitypub
|
|
```
|
|
|
|
For detailed troubleshooting, see `ACTIVITYPUB_TESTING_GUIDE.md` Part 5.
|
|
|
|
## 📖 Learning Path
|
|
|
|
### For Developers
|
|
1. Read `ACTIVITYPUB_IMPLEMENTATION.md` to understand the architecture
|
|
2. Read `ACTIVITYPUB_SUMMARY.md` to see what's implemented
|
|
3. Follow test scenarios in `ACTIVITYPUB_TESTING_GUIDE.md`
|
|
4. Use helper API in `ACTIVITYPUB_TESTING_HELPER_API.md` for testing
|
|
|
|
### For Testers
|
|
1. Start with `ACTIVITYPUB_TESTING_QUICKSTART.md`
|
|
2. Use command reference in `ACTIVITYPUB_TESTING_QUICKREF.md`
|
|
3. Track results with `ACTIVITYPUB_TESTING_RESULTS_TEMPLATE.md`
|
|
4. Report issues with details from logs
|
|
|
|
## 🎓 Success Criteria
|
|
|
|
### Minimum Viable
|
|
- WebFinger works
|
|
- Actor profile valid
|
|
- Follow relationships work
|
|
- Posts federate correctly
|
|
- HTTP signatures verified
|
|
|
|
### Production Ready
|
|
- Activity queue with retry
|
|
- Rate limiting
|
|
- Monitoring/alerting
|
|
- Admin interface
|
|
- Instance blocking
|
|
- Content moderation
|
|
|
|
## 🚨 Common Pitfalls
|
|
|
|
### Don't Forget
|
|
- ✅ Update `/etc/hosts` with both instances
|
|
- ✅ Run migrations before testing
|
|
- ✅ Check both instances are accessible
|
|
- ✅ Verify PostgreSQL is running
|
|
- ✅ Check logs when something fails
|
|
|
|
### Watch Out For
|
|
- ❌ Using `localhost` instead of `solar.local`
|
|
- ❌ Forgetting to restart after config changes
|
|
- ❌ Not waiting for Mastodon to start (2-5 minutes)
|
|
- ❌ Ignoring CORS errors in browser testing
|
|
- ❌ Testing with deleted/invisible posts
|
|
|
|
## 📚 Additional Resources
|
|
|
|
### Official Specs
|
|
- [ActivityPub W3C](https://www.w3.org/TR/activitypub/)
|
|
- [ActivityStreams](https://www.w3.org/TR/activitystreams-core/)
|
|
- [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
|
|
|
|
### Community Guides
|
|
- [Mastodon Federation](https://docs.joinmastodon.org/admin/federation/)
|
|
- [Federation Testing](https://docs.joinmastodon.org/spec/activitypub/)
|
|
|
|
### Tools
|
|
- [ActivityPub Playground](https://swicth.github.io/activity-pub-playground/)
|
|
- [FediTest](https://feditest.com/)
|
|
|
|
## 🆘 Support
|
|
|
|
If you encounter issues:
|
|
|
|
1. Check logs (both Solar Network and Mastodon)
|
|
2. Review troubleshooting section in the guide
|
|
3. Validate against success criteria
|
|
4. Check database state with queries
|
|
5. Review implementation docs
|
|
|
|
## ✨ Next Steps
|
|
|
|
After testing with self-hosted instance:
|
|
|
|
1. Get a public domain or use ngrok
|
|
2. Update `ActivityPub:Domain` in appsettings.json
|
|
3. Test with public Mastodon instances
|
|
4. Add more ActivityPub features (queue, retry, etc.)
|
|
5. Implement admin interface
|
|
6. Add monitoring and metrics
|
|
|
|
## 📞 File Reference
|
|
|
|
All files are in the root of the DysonNetwork project:
|
|
|
|
```
|
|
DysonNetwork/
|
|
├── ACTIVITYPUB_TESTING_INDEX.md # Start here!
|
|
├── ACTIVITYPUB_TESTING_QUICKSTART.md # Quick reference
|
|
├── ACTIVITYPUB_TESTING_GUIDE.md # Full guide
|
|
├── ACTIVITYPUB_TESTING_QUICKREF.md # Commands
|
|
├── ACTIVITYPUB_TESTING_HELPER_API.md # Test API
|
|
├── ACTIVITYPUB_TESTING_RESULTS_TEMPLATE.md
|
|
├── setup-activitypub-test.sh # Setup script
|
|
├── test-activitypub.sh # Test script
|
|
└── .env.testing.example # Config template
|
|
```
|
|
|
|
**Documentation files** (for reference):
|
|
```
|
|
DysonNetwork/
|
|
├── ACTIVITYPUB_IMPLEMENTATION.md # How it's implemented
|
|
├── ACTIVITYPUB_SUMMARY.md # Feature summary
|
|
└── ACTIVITYPUB_PLAN.md # Original plan
|
|
```
|
|
|
|
---
|
|
|
|
**Start here**: `ACTIVITYPUB_TESTING_INDEX.md`
|
|
|
|
**Good luck with your testing!** 🚀
|