prvng_extensions/taskservs/development/radicle/README.md

# Radicle Task Service

## Overview

The Radicle task service provides a complete installation and configuration of [Radicle](https://radicle.xyz/), a peer-to-peer code collaboration stack built on Git. Radicle enables developers to collaborate on code without relying on centralized platforms, using cryptographic identities and peer-to-peer networking.

## Features

### Core Capabilities
- **Peer-to-Peer Git Hosting** - Decentralized code repositories without central servers
- **Cryptographic Identities** - Secure, verifiable developer identities
- **Web Interface** - Optional HTTP daemon for browser-based access
- **Automatic Discovery** - No manual registry or complex setup required
- **Git Integration** - Works seamlessly with existing Git workflows

### Network Configuration
- **Configurable Ports** - Node, peer, and web interface ports
- **External Addresses** - Support for public IP announcement
- **Seed Nodes** - Connect to existing Radicle network
- **Timeout Configuration** - Customizable connection timeouts

### Security & Management
- **User Isolation** - Dedicated system user for Radicle services  
- **Systemd Integration** - Full service management and auto-start
- **Configurable Logging** - Trace to error level logging
- **Storage Management** - Dedicated storage paths and permissions

## Configuration

### Basic Configuration
```kcl
radicle: RadicleNode = {
    name: "my-radicle-node"
    version: "1.0.0"
    run_user: {
        name: "radicle"
        home: "/home/radicle"
    }
    bind_addr: "0.0.0.0"
    bind_port: 8776
    peer_port: 8777
    web_ui_port: 8080
    announce: true
}
```

### Advanced Configuration
```kcl
radicle: RadicleNode = {
    name: "enterprise-radicle"
    version: "1.0.0"
    run_user: {
        name: "radicle"
        group: "radicle"
        home: "/opt/radicle"
    }
    work_path: "/var/lib/radicle"
    storage_path: "/data/radicle/storage"
    bind_addr: "0.0.0.0"
    bind_port: 8776
    peer_port: 8777
    web_ui_port: 8080
    seeds: [
        "seed.radicle.garden:8776",
        "maple.radicle.garden:8776"
    ]
    external_addresses: [
        "203.0.113.1:8776"
    ]
    connect_timeout: 30
    announce: true
    log_level: "info"
}

httpd: RadicleHttpd = {
    enabled: true
    bind_addr: "0.0.0.0"
    bind_port: 8080
    assets_path: "/usr/share/radicle/assets"
}
```

## Usage

### Deploy Radicle Node
```bash
./core/nulib/provisioning taskserv create radicle --infra <infrastructure-name>
```

### List Available Task Services
```bash
./core/nulib/provisioning taskserv list
```

### SSH to Radicle Server
```bash
./core/nulib/provisioning server ssh <radicle-server>
```

### Service Management
```bash
# Check Radicle node status
systemctl status radicle-node

# Start/stop Radicle node
systemctl start radicle-node
systemctl stop radicle-node

# Check Radicle HTTP daemon status
systemctl status radicle-httpd

# View Radicle logs
journalctl -u radicle-node -f
journalctl -u radicle-httpd -f
```

### Access Web Interface
1. **Open browser** to `http://<server-ip>:8080`
2. **Create identity** if first time using Radicle
3. **Initialize repositories** and start collaborating

### Command Line Usage
```bash
# Switch to radicle user
sudo -u radicle -i

# Initialize a new project
rad init

# Clone a project
rad clone <project-urn>

# Push to Radicle network
rad push

# List local projects
rad project list

# Show node information
rad node info

# Show connected peers
rad node peers
```

## Architecture

### Network Topology
- **Node Port (8776)** - Main Radicle node communication
- **Peer Port (8777)** - Peer-to-peer synchronization
- **Web UI Port (8080)** - HTTP daemon for web interface

### File Structure
```
/var/lib/radicle/           # Main working directory
├── storage/                # Repository storage
├── keys/                   # Node identity keys
└── config.json            # Node configuration

/etc/radicle/               # Configuration directory
├── node.conf              # Node settings
└── httpd.conf             # HTTP daemon settings

/home/radicle/              # User home directory
├── .radicle/              # User Radicle configuration
└── projects/              # Local project checkouts
```

## Supported Operating Systems

- Ubuntu 20.04+ / Debian 11+
- CentOS 8+ / RHEL 8+ / Fedora 35+

## System Requirements

### Minimum Requirements
- **RAM**: 1GB (2GB recommended)
- **Storage**: 10GB (varies with repository size)
- **CPU**: 1 core (2 cores recommended)
- **Network**: Internet access for peer discovery

### Network Requirements
- **Outbound**: TCP ports 8776, 8777 for peer communication
- **Inbound**: TCP ports 8776, 8777, 8080 (configurable)
- **Firewall**: Allow configured ports through firewall

## Troubleshooting

### Service Issues
```bash
# Check Radicle node status
systemctl status radicle-node

# Restart Radicle services
systemctl restart radicle-node radicle-httpd

# Check for configuration errors
rad node config --check

# View detailed logs
journalctl -u radicle-node -n 100
```

### Network Connectivity
```bash
# Test peer connectivity
rad node peers

# Check if ports are listening
netstat -tlnp | grep :8776
netstat -tlnp | grep :8777

# Test external connectivity
telnet <external-ip> 8776
```

### Storage Issues
```bash
# Check storage permissions
ls -la /var/lib/radicle/storage/

# Check disk space
df -h /var/lib/radicle/

# Verify storage integrity
rad storage check
```

### Identity Issues
```bash
# Show node identity
rad node identity

# Regenerate identity (destructive!)
rad node identity --regenerate

# Export identity for backup
rad node identity --export > identity-backup.json
```

## Security Considerations

### Network Security
- **Firewall Rules** - Limit access to necessary ports only
- **Private Networks** - Consider VPN for internal-only deployment
- **DDoS Protection** - Implement rate limiting for public nodes

### Identity Management
- **Key Backup** - Backup node identity keys securely
- **Access Control** - Limit shell/SSH access to radicle user
- **Regular Updates** - Keep Radicle software updated

### Data Protection
- **Storage Encryption** - Consider filesystem-level encryption
- **Backup Strategy** - Regular backup of repository storage
- **Network Monitoring** - Monitor for unusual network activity

## Integration Examples

### CI/CD Integration
```bash
# In CI/CD pipeline
rad clone <project-urn>
cd <project-name>
# Run tests, builds, etc.
rad push  # Push results back to network
```

### Git Integration
```bash
# Add Radicle as Git remote
git remote add radicle <project-urn>

# Push to both origins
git push origin main
git push radicle main

# Fetch from Radicle network
git fetch radicle
```

### Development Workflow
```bash
# Developer workflow
rad init my-project
cd my-project
git add . && git commit -m "Initial commit"
rad push

# Share project URN with collaborators
rad project show
```

## Performance Optimization

### For High-Traffic Nodes
- Increase file descriptor limits in systemd service
- Use SSD storage for better I/O performance
- Configure higher connection timeouts for slow networks
- Monitor resource usage and scale accordingly

### For Low-Resource Systems
- Reduce logging verbosity to 'warn' or 'error'
- Limit concurrent connections
- Use smaller timeout values
- Consider disabling HTTP daemon if not needed

## Migration and Backup

### Backup Procedure
```bash
# Stop services
systemctl stop radicle-node radicle-httpd

# Backup storage and keys
tar -czf radicle-backup-$(date +%Y%m%d).tar.gz \
    /var/lib/radicle/storage \
    /var/lib/radicle/keys \
    /etc/radicle/

# Restart services
systemctl start radicle-node radicle-httpd
```

### Migration Steps
1. **Stop services** on old server
2. **Backup data** using procedure above
3. **Deploy new server** with same configuration
4. **Restore data** to new server
5. **Update DNS/firewall** rules as needed
6. **Verify connectivity** and peer discovery

## Resources

- **Official Documentation**: [docs.radicle.xyz](https://docs.radicle.xyz)
- **GitHub Repository**: [radicle-dev/radicle-node](https://github.com/radicle-dev/radicle-node)
- **Community**: [radicle.community](https://radicle.community)
- **Seeds**: Default seed nodes for network bootstrapping