v0.3.0 - Complete deployment documentation and examples - Added comprehensive deployment guide, automated deployment scripts, nginx SSL proxy setup, backup automation, and monitoring tools. Includes VPS deployment, cloud platform guides, and practical examples for production deployment of event-based configuration system.

2025-09-06 20:19:12 -04:00
parent a02c1204ce
commit c1de1bb480
39 changed files with 6109 additions and 2452 deletions
--- a/README.md
+++ b/README.md
@@ -1,13 +1,273 @@
-A nostr relay in C with sqlite on the back end.
+# C Nostr Relay - Event-Based Configuration System
+
+A high-performance Nostr relay implemented in C with SQLite backend, featuring a revolutionary **zero-configuration** approach using event-based configuration management.
+
+## 🌟 Key Features
+
+- **🔧 Zero Configuration**: No config files or command line arguments needed
+- **🔑 Event-Based Config**: All settings stored as kind 33334 Nostr events
+- **🚀 Real-Time Updates**: Configuration changes applied instantly via WebSocket
+- **🛡️ Cryptographic Security**: Configuration events cryptographically signed and validated
+- **📊 SQLite Backend**: High-performance event storage with optimized schema
+- **🔄 Auto Key Generation**: Secure admin and relay keypairs generated on first startup
+- **💾 Database Per Relay**: Each relay instance uses `<relay_pubkey>.nrdb` database naming
+
+## 🚀 Quick Start
+
+### 1. Build the Relay
+```bash
+git clone <repository-url>
+cd c-relay
+git submodule update --init --recursive
+make
+```
+
+### 2. Start the Relay
+```bash
+./build/c_relay_x86
+```
+
+**That's it!** No configuration files, no command line arguments needed.
+
+### 3. Save Your Admin Keys (IMPORTANT!)
+On first startup, the relay will display:
+
+```
+=================================================================
+IMPORTANT: SAVE THIS ADMIN PRIVATE KEY SECURELY!
+=================================================================
+Admin Private Key: f8491814ea288260dad2ab52c09b3b037e75e83e8b24feb9bdc328423922be44
+Admin Public Key:  07fc2cdd8bdc0c60eefcc9e37e67fef88206bc84fadb894c283b006554ac687b
+
+Relay Private Key: a1b2c3d4e5f6...
+Relay Public Key:  1a2b3c4d5e6f...
+
+Database: dc9a93fd0ffba7041f6df0602e5021913a42fcaf6dbf40f43ecdc011177b4d94.nrdb
+=================================================================
+```
+
+⚠️ **Save the admin private key securely** - it's needed to update relay configuration and is only displayed once!
+
+## 📋 System Requirements
+
+- **OS**: Linux, macOS, or Windows (WSL)
+- **Dependencies**: 
+  - SQLite 3
+  - libwebsockets
+  - OpenSSL/LibreSSL
+  - libsecp256k1
+  - libcurl
+  - zlib
+
+## 🏗️ Event-Based Configuration System
+
+### How It Works
+
+Traditional Nostr relays require configuration files, environment variables, or command line arguments. This relay uses a **revolutionary approach**:
+
+1. **First-Time Startup**: Generates cryptographically secure admin and relay keypairs
+2. **Database Creation**: Creates `<relay_pubkey>.nrdb` database file
+3. **Default Configuration**: Creates initial kind 33334 configuration event with sensible defaults
+4. **Real-Time Updates**: Administrators send new kind 33334 events to update configuration
+5. **Instant Application**: Changes are applied immediately without restart
+
+### Configuration Updates
+
+To update relay configuration, send a signed kind 33334 event:
+
+```json
+{
+  "kind": 33334,
+  "content": "C Nostr Relay Configuration",
+  "tags": [
+    ["d", "<relay_pubkey>"],
+    ["relay_description", "My awesome Nostr relay"],
+    ["max_subscriptions_per_client", "25"],
+    ["pow_min_difficulty", "16"],
+    ["nip40_expiration_enabled", "true"]
+  ],
+  "created_at": 1234567890,
+  "pubkey": "<admin_pubkey>",
+  "id": "...",
+  "sig": "..."
+}
+```
+
+Send this event to your relay via WebSocket, and changes are applied instantly.
+
+### Configurable Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `relay_description` | Relay description (NIP-11) | "C Nostr Relay" |
+| `relay_contact` | Admin contact info | "" |
+| `max_subscriptions_per_client` | Max subscriptions per client | "25" |
+| `max_total_subscriptions` | Total subscription limit | "5000" |
+| `pow_min_difficulty` | NIP-13 PoW difficulty | "0" |
+| `pow_mode` | PoW validation mode | "optional" |
+| `nip40_expiration_enabled` | Enable NIP-40 expiration | "true" |
+| `nip40_expiration_strict` | Strict expiration mode | "false" |
+| `max_message_length` | Max message size | "65536" |
+| `max_event_tags` | Max tags per event | "2000" |
+| `max_content_length` | Max content length | "65536" |
+
+## 🔧 Deployment
+
+### Manual Installation
+```bash
+# Build the relay
+make
+
+# Run directly
+./build/c_relay_x86
+```
+
+### SystemD Service (Recommended)
+```bash
+# Install as system service
+sudo systemd/install-service.sh
+
+# Start the service
+sudo systemctl start c-relay
+
+# Enable auto-start on boot
+sudo systemctl enable c-relay
+
+# View logs
+sudo journalctl -u c-relay -f
+```
+
+See [`systemd/README.md`](systemd/README.md) for detailed deployment documentation.
+
+### Docker (Coming Soon)
+Docker support is planned for future releases.
+
+## 📊 Database Schema
+
+The relay uses an optimized SQLite schema (version 4) with these key features:
+
+- **Event-based storage**: All Nostr events in single `events` table
+- **JSON tags support**: Native JSON storage for event tags
+- **Performance optimized**: Multiple indexes for fast queries
+- **Subscription logging**: Optional detailed subscription analytics
+- **Auto-cleanup**: Automatic ephemeral event cleanup
+- **Replaceable events**: Proper handling of replaceable/addressable events
+
+## 🛡️ Security Features
+
+- **Cryptographic validation**: All configuration events cryptographically verified
+- **Admin-only config**: Only authorized admin pubkey can update configuration
+- **Signature verification**: Uses `nostr_verify_event_signature()` for validation
+- **Event structure validation**: Complete event structure validation
+- **Secure key generation**: Uses `/dev/urandom` for cryptographically secure keys
+- **No secrets storage**: Admin private key never stored on disk
+
+## 🔌 Network Configuration
+
+- **Default Port**: 8888 (WebSocket)
+- **Protocol**: WebSocket with Nostr message format
+- **Endpoints**: 
+  - `ws://localhost:8888` - WebSocket relay
+  - `http://localhost:8888` - NIP-11 relay information (HTTP GET)
+
+## 🏃‍♂️ Usage Examples
+
+### Connect with a Nostr Client
+```javascript
+const relay = new WebSocket('ws://localhost:8888');
+relay.send(JSON.stringify(["REQ", "sub1", {"kinds": [1], "limit": 10}]));
+```
+
+### Update Configuration (using `nostrtool` or similar)
+```bash
+# Create configuration event with nostrtool
+nostrtool event --kind 33334 --content "Updated config" \
+  --tag d <relay_pubkey> \
+  --tag relay_description "My updated relay" \
+  --private-key <admin_private_key>
+
+# Send to relay
+nostrtool send ws://localhost:8888 <event_json>
+```
+
+## 📈 Monitoring and Analytics
+
+### View Relay Status
+```bash
+# Check if relay is running
+ps aux | grep c_relay
+
+# Check network port
+netstat -tln | grep 8888
+
+# View recent logs
+tail -f relay.log
+```
+
+### Database Analytics
+```bash
+# Connect to relay database
+sqlite3 <relay_pubkey>.nrdb
+
+# View relay statistics
+SELECT * FROM event_stats;
+
+# View configuration events
+SELECT * FROM configuration_events;
+
+# View recent events
+SELECT * FROM recent_events LIMIT 10;
+```
+
+## 🧪 Testing
+
+### Run Error Handling Tests
+```bash
+# Comprehensive test suite
+tests/event_config_tests.sh
+
+# Quick validation tests
+tests/quick_error_tests.sh
+```
+
+### Manual Testing
+```bash
+# Test WebSocket connection
+wscat -c ws://localhost:8888
+
+# Test NIP-11 information
+curl http://localhost:8888
+```
+
+## 🔧 Development
+
+### Build from Source
+```bash
+git clone <repository-url>
+cd c-relay
+git submodule update --init --recursive
+make clean && make
+```
+
+### Debug Build
+```bash
+make debug
+gdb ./build/c_relay_x86
+```
+
+### Contributing
+1. Fork the repository
+2. Create a feature branch
+3. Make changes with tests
+4. Submit a pull request
+
+## 📜 Supported NIPs

 <!--
 NOTE FOR ASSISTANTS: When updating the NIPs checklist below, ONLY change [ ] to [x] to mark as complete.
 Do NOT modify the formatting, add emojis, or change the text. Keep the simple format consistent.
 -->

-
-### [NIPs](https://github.com/nostr-protocol/nips)
-
 - [x] NIP-01: Basic protocol flow implementation
 - [x] NIP-09: Event deletion
 - [x] NIP-11: Relay information document
@@ -17,6 +277,67 @@ Do NOT modify the formatting, add emojis, or change the text. Keep the simple fo
 - [x] NIP-33: Parameterized Replaceable Events
 - [x] NIP-40: Expiration Timestamp
 - [ ] NIP-42: Authentication of clients to relays
- [ ] NIP-45: Counting results.
- [ ] NIP-50: Keywords filter.
+- [ ] NIP-45: Counting results
+- [ ] NIP-50: Keywords filter
 - [ ] NIP-70: Protected Events
+
+## 🆘 Troubleshooting
+
+### Common Issues
+
+**Relay won't start**
+```bash
+# Check for port conflicts
+netstat -tln | grep 8888
+
+# Check permissions
+ls -la build/c_relay_x86
+
+# Check dependencies
+ldd build/c_relay_x86
+```
+
+**Lost admin private key**
+- If you lose the admin private key, you cannot update configuration
+- You must delete the database file and restart (loses all events)
+- The relay will generate new keys on first startup
+
+**Database corruption**
+```bash
+# Check database integrity
+sqlite3 <relay_pubkey>.nrdb "PRAGMA integrity_check;"
+
+# If corrupted, remove database (loses all events)
+rm <relay_pubkey>.nrdb*
+./build/c_relay_x86  # Will create fresh database
+```
+
+**Configuration not updating**
+- Ensure configuration events are properly signed
+- Check that admin pubkey matches the one from first startup
+- Verify WebSocket connection is active
+- Check relay logs for validation errors
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🤝 Support
+
+- **Issues**: Report bugs and feature requests on GitHub
+- **Documentation**: See `docs/` directory for technical details
+- **Deployment**: See `systemd/README.md` for production deployment
+- **Community**: Join the Nostr development community
+
+## 🚀 Future Roadmap
+
+- [ ] Docker containerization
+- [ ] NIP-42 authentication support
+- [ ] Advanced analytics dashboard
+- [ ] Clustering support for high availability
+- [ ] Performance optimizations
+- [ ] Additional NIP implementations
+
+---
+
+**The C Nostr Relay represents the future of Nostr infrastructure - zero configuration, event-based management, and cryptographically secure administration.**