/ RADICLE_PUSH_GUIDE.md
RADICLE_PUSH_GUIDE.md
1 # 🌐 Radicle Push Guide - ComposableScan 2 3 ## What is Radicle? 4 5 **Radicle** is a **peer-to-peer, decentralized code collaboration platform** - an open-source alternative to GitHub that gives you full ownership of your code. 6 7 - 🌐 **Decentralized**: No central server, you run your own node 8 - 🔐 **Censorship-resistant**: Nobody can take down your code 9 - 🔑 **Cryptographic identities**: Public-key based authentication 10 - 🚀 **Built on Git**: Uses Git for data transfer 11 - 💾 **Offline-first**: Work without internet, sync when online 12 13 **Web Interface**: [https://app.radicle.xyz](https://app.radicle.xyz) 14 15 --- 16 17 ## 🚀 Quick Start 18 19 ### Option 1: Using Radicle Desktop (Easiest) 20 21 1. **Download Radicle Desktop** 22 - Visit: [https://radicle.xyz](https://radicle.xyz) 23 - Download for your platform (Linux, macOS, Windows) 24 - Install and run 25 26 2. **Create Identity** 27 - Open Radicle Desktop 28 - Create your profile (alias + passphrase) 29 - This generates your cryptographic identity 30 31 3. **Add Repository** 32 - Click "Add Project" or "Import Repository" 33 - Select your ComposableScan folder 34 - Follow prompts to publish 35 36 ### Option 2: Using CLI (Advanced) 37 38 #### Step 1: Install Radicle CLI 39 40 ```bash 41 # Install via curl 42 curl -sSf https://radicle.xyz/install | sh 43 44 # Or download from https://radicle.xyz 45 ``` 46 47 **Requirements**: 48 - Git 2.34.0 or later 49 - ssh-agent running 50 - Linux, macOS, or BSD 51 52 #### Step 2: Create Your Identity 53 54 ```bash 55 # Initialize Radicle and create identity 56 rad auth 57 58 # You'll be prompted for: 59 # - Alias (your username) 60 # - Passphrase (to protect your keys) 61 ``` 62 63 This creates: 64 - Cryptographic key pair in `~/.radicle` 65 - Your DID (Decentralized Identifier) 66 67 Example output (DIDs shown are examples only): 68 ``` 69 ✓ Creating your Radicle identity... 70 ✓ Your DID: did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK 71 Note: This is an example DID, yours will be different 72 ``` 73 74 #### Step 3: Initialize Your Repository 75 76 ```bash 77 # Navigate to your project 78 cd /home/eyawaa/composablescan 79 80 # Initialize Radicle for this repository 81 rad init 82 83 # You'll be prompted for: 84 # - Project name: ComposableScan 85 # - Description: Espresso Network Explorer with Transaction Correlation Tools 86 # - Default branch: main (or your current branch) 87 ``` 88 89 This creates a **Repository ID (RID)** unique to your project. 90 91 #### Step 4: Push to Radicle Network 92 93 ```bash 94 # First, make sure all changes are committed 95 git status 96 git add . 97 git commit -m "feat: add transaction correlation tool" 98 99 # Push to Radicle 100 rad push 101 ``` 102 103 This publishes your repository to the Radicle network! 104 105 --- 106 107 ## 📋 Complete Step-by-Step Guide 108 109 ### Prerequisites 110 111 ```bash 112 # Check Git version (need 2.34.0+) 113 git --version 114 115 # Check if ssh-agent is running 116 ssh-add -l 117 118 # If not running, start it 119 eval "$(ssh-agent -s)" 120 ``` 121 122 ### Step 1: Install Radicle 123 124 ```bash 125 # Download and install 126 curl -sSf https://radicle.xyz/install | sh 127 128 # Add to PATH (add to ~/.bashrc or ~/.zshrc) 129 export PATH="$HOME/.radicle/bin:$PATH" 130 131 # Reload shell 132 source ~/.bashrc 133 134 # Verify installation 135 rad --version 136 ``` 137 138 ### Step 2: Set Up Identity 139 140 ```bash 141 # Create identity 142 rad auth 143 144 # Example session: 145 $ rad auth 146 ✓ Initializing your radicle 🌱 identity 147 ⚠ Creating your Radicle identity... 148 Enter an alias for your identity: your-username 149 Enter a passphrase: ******** 150 Confirm passphrase: ******** 151 ✓ Identity created: did:key:z6Mk... 152 ``` 153 154 ### Step 3: Initialize Repository 155 156 ```bash 157 cd /home/eyawaa/composablescan 158 159 # Initialize Radicle 160 rad init 161 162 # Example session: 163 $ rad init 164 ✓ Initializing radicle 🌱 project 165 Enter a name for your project: ComposableScan 166 Enter a description: Espresso Network Explorer with Transaction Correlation Tools 167 Default branch (main): main 168 ✓ Project initialized: rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji 169 ``` 170 171 This creates a **Radicle remote** in your `.git/config`: 172 173 ```ini 174 [remote "rad"] 175 url = rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji 176 fetch = +refs/heads/*:refs/remotes/rad/* 177 ``` 178 179 ### Step 4: Verify Setup 180 181 ```bash 182 # Check Radicle status 183 rad self 184 185 # Output shows: 186 # - Your DID 187 # - Your alias 188 # - Node ID 189 # - Storage location 190 191 # Check remotes 192 git remote -v 193 194 # You should see: 195 # origin https://github.com/... (existing) 196 # rad rad://z42hL2... (new) 197 ``` 198 199 ### Step 5: Publish Repository 200 201 ```bash 202 # Stage and commit all changes 203 git status 204 git add . 205 git commit -m "feat: initial Radicle publication 206 207 - Add transaction correlation tool 208 - Update documentation 209 - Configure multi-network support" 210 211 # Push to Radicle 212 rad push 213 ``` 214 215 **What happens**: 216 1. Your code is published to your local Radicle node 217 2. Your node announces the repository to peers 218 3. Other nodes can discover and clone your repository 219 220 ### Step 6: Share Your Repository 221 222 After pushing, you'll get a **Repository ID (RID)**: 223 224 ``` 225 Repository ID: rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji 226 ``` 227 228 **Share this with others:** 229 230 ```bash 231 # Others can clone your repository 232 rad clone rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji 233 234 # Or via the web interface 235 https://app.radicle.xyz/nodes/<your-node-id>/rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji 236 ``` 237 238 --- 239 240 ## 🌐 Using the Web Interface 241 242 ### Step 1: Run HTTP Daemon 243 244 To use [app.radicle.xyz](https://app.radicle.xyz) with your local node: 245 246 ```bash 247 # Start the HTTP daemon (serves your local node to web interface) 248 rad-httpd 249 250 # Or specify port 251 rad-httpd --listen 0.0.0.0:8080 252 ``` 253 254 ### Step 2: Connect Web Interface 255 256 1. Go to [https://app.radicle.xyz](https://app.radicle.xyz) 257 2. Click "Connect to Node" 258 3. Enter your node address: `http://localhost:8080` 259 4. Browse your repositories in the web UI 260 261 ### Step 3: Share via Web 262 263 Your repository will be accessible at: 264 ``` 265 https://app.radicle.xyz/nodes/<node-id>/<repository-id> 266 ``` 267 268 --- 269 270 ## 🔄 Working with Radicle 271 272 ### Daily Workflow 273 274 ```bash 275 # 1. Make changes to your code 276 vim src/some-file.ts 277 278 # 2. Commit as usual 279 git add . 280 git commit -m "feat: add new feature" 281 282 # 3. Push to Radicle 283 rad push 284 285 # 4. Push to GitHub (if you want both) 286 git push origin main 287 ``` 288 289 ### Syncing with Others 290 291 ```bash 292 # Fetch updates from peers 293 rad sync 294 295 # Pull changes 296 rad pull 297 298 # Push your changes 299 rad push 300 ``` 301 302 ### Cloning from Radicle 303 304 ```bash 305 # Clone a repository from Radicle 306 rad clone rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji 307 308 # Clone and give it a custom name 309 rad clone rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji composablescan 310 ``` 311 312 --- 313 314 ## 📊 Comparison: Radicle vs GitHub 315 316 | Feature | GitHub | Radicle | 317 |---------|--------|---------| 318 | **Hosting** | Centralized (GitHub servers) | Decentralized (P2P nodes) | 319 | **Ownership** | GitHub owns infrastructure | You own your node | 320 | **Censorship** | Can be taken down | Censorship-resistant | 321 | **Access** | Requires internet | Works offline | 322 | **Authentication** | Username/password | Cryptographic keys | 323 | **Cost** | Free (with limits) | Free (run your own node) | 324 | **Discovery** | Central search | Peer gossip protocol | 325 | **Web UI** | Always available | Requires running httpd | 326 327 --- 328 329 ## 🔧 Advanced Configuration 330 331 ### Configure Seed Nodes 332 333 Seed nodes help with discovery and availability: 334 335 ```bash 336 # Add a seed node for better replication 337 rad node config --seed seed.radicle.xyz 338 339 # List configured seeds 340 rad node config --list 341 ``` 342 343 ### Run as a Seed Node 344 345 Help the network by running a public seed: 346 347 ```bash 348 # Configure your node as a seed 349 rad node config --public 350 351 # Set external address 352 rad node config --external-address your-ip:8776 353 ``` 354 355 ### Configure Storage 356 357 ```bash 358 # Check storage location 359 rad self --home 360 361 # Change storage location 362 export RAD_HOME=/path/to/radicle/storage 363 ``` 364 365 --- 366 367 ## 🐛 Troubleshooting 368 369 ### Issue: "rad: command not found" 370 371 **Solution**: Add to PATH 372 373 ```bash 374 export PATH="$HOME/.radicle/bin:$PATH" 375 echo 'export PATH="$HOME/.radicle/bin:$PATH"' >> ~/.bashrc 376 ``` 377 378 ### Issue: "ssh-agent not running" 379 380 **Solution**: Start ssh-agent 381 382 ```bash 383 eval "$(ssh-agent -s)" 384 ssh-add 385 ``` 386 387 ### Issue: "Git version too old" 388 389 **Solution**: Update Git to 2.34.0+ 390 391 ```bash 392 # Ubuntu/Debian 393 sudo apt update 394 sudo apt install git 395 396 # macOS 397 brew install git 398 ``` 399 400 ### Issue: "Cannot connect to peers" 401 402 **Solution**: Check firewall and port 403 404 ```bash 405 # Default Radicle port is 8776 406 # Open firewall 407 sudo ufw allow 8776/tcp 408 409 # Check if node is listening 410 ss -tlnp | grep 8776 411 ``` 412 413 ### Issue: "rad push fails" 414 415 **Solution**: Check you've committed changes 416 417 ```bash 418 # Must commit before pushing 419 git status 420 git add . 421 git commit -m "your message" 422 rad push 423 ``` 424 425 --- 426 427 ## 📚 Additional Resources 428 429 ### Official Documentation 430 - **Homepage**: [https://radicle.xyz](https://radicle.xyz) 431 - **User Guide**: [https://radicle.xyz/guides/user](https://radicle.xyz/guides/user) 432 - **Protocol Guide**: [https://radicle.xyz/guides/protocol](https://radicle.xyz/guides/protocol) 433 434 ### Community 435 - **Discord**: Check Radicle website for invite 436 - **Matrix**: #radicle:matrix.org 437 - **GitHub**: [https://github.com/radicle-dev](https://github.com/radicle-dev) 438 439 ### Video Tutorials 440 - **"How to Replace GitHub with Radicle"** by Nader Dabit 441 - [YouTube Link](https://www.youtube.com/watch?v=Y8pulFGOrMw) 442 - Covers installation, authentication, pushing, and cloning 443 444 --- 445 446 ## 🎯 Quick Command Reference 447 448 ```bash 449 # Identity 450 rad auth # Create identity 451 rad self # View your identity 452 453 # Repository 454 rad init # Initialize repository 455 rad push # Push to network 456 rad pull # Pull updates 457 rad sync # Sync with peers 458 rad clone <rid> # Clone repository 459 460 # Node 461 rad node start # Start node 462 rad node stop # Stop node 463 rad node status # Check status 464 rad-httpd # Start web interface 465 466 # Information 467 rad inspect # Show repository info 468 rad remote # List remotes 469 rad ls # List local repositories 470 ``` 471 472 --- 473 474 ## ✅ Checklist: Publishing to Radicle 475 476 - [ ] Install Radicle CLI (`curl -sSf https://radicle.xyz/install | sh`) 477 - [ ] Check Git version (2.34.0+) 478 - [ ] Start ssh-agent (`eval "$(ssh-agent -s)"`) 479 - [ ] Create identity (`rad auth`) 480 - [ ] Navigate to repository (`cd /home/eyawaa/composablescan`) 481 - [ ] Initialize Radicle (`rad init`) 482 - [ ] Commit all changes (`git commit`) 483 - [ ] Push to Radicle (`rad push`) 484 - [ ] Share your Repository ID with others 485 - [ ] (Optional) Start httpd for web access (`rad-httpd`) 486 487 --- 488 489 ## 🌟 Benefits of Using Radicle 490 491 1. **True Ownership**: You control your code and infrastructure 492 2. **Censorship Resistant**: No single entity can take down your repository 493 3. **Privacy**: No tracking or analytics 494 4. **Offline First**: Work without internet, sync later 495 5. **Open Source**: Fully transparent and auditable 496 6. **No Vendor Lock-in**: Standard Git, can migrate anytime 497 7. **Community Governed**: Decentralized decision making 498 499 --- 500 501 ## 🚀 Next Steps 502 503 After publishing to Radicle: 504 505 1. **Share your RID** with the community 506 2. **Run a seed node** to help the network 507 3. **Document your Radicle repository** in README 508 4. **Use both GitHub and Radicle** for maximum reach 509 5. **Contribute to Radicle** development 510 511 --- 512 513 ## 📝 Adding Radicle Info to README 514 515 Add this section to your project README: 516 517 ```markdown 518 ## 🌐 Decentralized Hosting 519 520 This repository is also available on Radicle, a peer-to-peer code collaboration platform: 521 522 **Repository ID**: rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji 523 524 Clone via Radicle: 525 \`\`\`bash 526 rad clone rad:z42hL2jL4XNk6K8oHQaSWfMgCL7ji 527 \`\`\` 528 529 Learn more about Radicle: [https://radicle.xyz](https://radicle.xyz) 530 ``` 531 532 --- 533 534 **Your repository is now ready to be published to the decentralized web! 🌐** 535 536 **Radicle = True code ownership + Censorship resistance + Peer-to-peer collaboration**