diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..ff212a6 --- /dev/null +++ b/README.md @@ -0,0 +1,275 @@ +# RegFlow + +A domain registration and DNS management automation tool that integrates with Namecheap and Cloudflare APIs. + +## Features + +- **Idempotent domain setup** - Safe to run multiple times +- **Domain registration** with Namecheap (with strict confirmation) +- **Cloudflare zone management** - Automatic zone creation +- **Nameserver synchronization** - Keeps Namecheap and Cloudflare in sync +- **Status checking** - View current domain configuration +- **Dry-run mode** - Preview changes without making them +- **Comprehensive logging** - Track all operations + +## Installation + +### Prerequisites + +- Python 3.8.1 or higher +- Namecheap API access (API key, username, client IP) +- Cloudflare API access (API token) + +### Install from source + +```bash +git clone <repository-url> +cd regflow +pip install -e . +``` + +## Configuration + +Create a `.env` file in your project directory: + +```bash +# Namecheap API Configuration +NAMECHEAP_API_KEY=your_namecheap_api_key +NAMECHEAP_API_USER=your_namecheap_api_user +NAMECHEAP_USERNAME=your_namecheap_username +NAMECHEAP_CLIENT_IP=your_public_ip_address + +# Cloudflare API Configuration +CLOUDFLARE_API_TOKEN=your_cloudflare_api_token +``` + +### Getting API Credentials + +#### Namecheap +1. Log in to your Namecheap account +2. Go to Profile → Tools → API Access +3. Enable API access and whitelist your IP +4. Note your API Key, Username, and Client IP + +#### Cloudflare +1. Log in to your Cloudflare account +2. Go to My Profile → API Tokens +3. Create a token with these permissions: + - Zone:Edit, Zone:Read, DNS:Edit + - Include: All zones + +## Usage + +### Basic Commands + +```bash +# Check domain status +regflow example.com --status + +# Setup domain (idempotent) +regflow example.com --setup + +# Dry run (preview changes) +regflow example.com --setup --dry-run + +# Register new domain (requires confirmation) +regflow example.com --setup --force-registration + +# Setup without worker subdomain +regflow example.com --setup --no-workers +``` + +### Command Options + +| Option | Description | +|--------|-------------| +| `--status` | Show current domain status across all services | +| `--setup` | Set up domain (default action if no option specified) | +| `--dry-run` | Show what would be done without making changes | +| `--force-registration` | Allow domain registration (costs money!) | +| `--no-workers` | Skip worker subdomain setup | + +### Status Output + +The status command shows: +- ✅ Domain registration status in Namecheap +- ✅ Cloudflare zone existence and details +- ✅ Current nameservers from both services +- ✅ Nameserver synchronization status + +Example output: +``` +=== Domain Status: example.com === +✓ Domain is registered in Namecheap +✓ Cloudflare zone exists (ID: abc123, Status: active) +Namecheap nameservers: ns1.cloudflare.com, ns2.cloudflare.com +Cloudflare nameservers: ns1.cloudflare.com, ns2.cloudflare.com +✓ Nameservers are properly configured +================================================== +``` + +## Domain Setup Process + +RegFlow follows this idempotent workflow: + +1. **Domain Registration Check** - Verify domain is registered in Namecheap +2. **Domain Registration** - Register domain if needed (with user confirmation) +3. **Cloudflare Zone Creation** - Create zone if it doesn't exist +4. **Nameserver Retrieval** - Get Cloudflare nameservers +5. **Nameserver Synchronization** - Update Namecheap nameservers if needed +6. **DNS Record Setup** - Configure basic DNS records +7. **Worker Subdomain** - Optional app.domain.com setup + +## Safety Features + +### Domain Registration Protection +- Requires explicit `--force-registration` flag +- Multiple confirmation prompts +- Shows exact cost before charging +- Dry-run mode available + +### Idempotent Operations +- Safe to run multiple times +- Only makes necessary changes +- Skips completed steps +- Preserves existing configuration + +### Error Handling +- Graceful API failure handling +- Clear error messages +- Rollback on critical failures +- Detailed logging + +## Examples + +### New Domain Registration +```bash +# Check if domain is available +regflow newdomain.com --status + +# Register and set up completely (with confirmation) +regflow newdomain.com --setup --force-registration + +# Preview the registration process +regflow newdomain.com --setup --force-registration --dry-run +``` + +### Existing Domain Management +```bash +# Check current configuration +regflow existingdomain.com --status + +# Fix nameserver configuration +regflow existingdomain.com --setup + +# Set up without worker subdomain +regflow existingdomain.com --setup --no-workers +``` + +### Troubleshooting Setup +```bash +# See what would be changed +regflow domain.com --setup --dry-run + +# Check detailed status +regflow domain.com --status + +# Force nameserver update +regflow domain.com --setup +``` + +## Development + +### Running Tests + +```bash +# Run all tests +pytest regflow/tests/ + +# Run specific test category +pytest regflow/tests/ -k "nameserver" + +# Run with verbose output +pytest regflow/tests/ -v +``` + +### Project Structure + +``` +regflow/ +├── __init__.py +├── config.py # Configuration management +├── domains.py # Main domain orchestration +├── providers/ +│ ├── namecheap.py # Namecheap API client +│ ├── cloudflare.py # Cloudflare API client +│ └── __init__.py +└── tests/ + ├── test_integration.py # Integration tests + └── __init__.py +``` + +### Adding New Providers + +1. Create new provider module in `regflow/providers/` +2. Implement required methods (register, configure, status) +3. Add integration to `domains.py` +4. Add tests to `test_integration.py` + +## Troubleshooting + +### Common Issues + +**API Authentication Errors** +- Verify API credentials in `.env` +- Check IP whitelist for Namecheap +- Verify Cloudflare token permissions + +**Domain Not Found** +- Ensure domain is registered in Namecheap account +- Check domain spelling and TLD +- Verify API access to domain + +**Nameserver Issues** +- Allow up to 24 hours for nameserver propagation +- Check domain registrar settings +- Verify Cloudflare zone is active + +### Error Messages + +| Error | Solution | +|-------|----------| +| `Missing required API credentials` | Add all required variables to `.env` | +| `Domain not registered and force_registration not enabled` | Use `--force-registration` to register | +| `Cannot retrieve nameservers` | Check API credentials and domain ownership | +| `Insufficient balance` | Add funds to Namecheap account | + +## API Rate Limits + +- **Namecheap**: No official limits, but be respectful +- **Cloudflare**: 1200 requests per 5 minutes per token + +## Security Notes + +- Store API credentials securely +- Use environment variables, not hardcoded values +- Regular credential rotation recommended +- Enable two-factor authentication on provider accounts + +## Contributing + +1. Fork the repository +2. Create a feature branch +3. Add tests for new functionality +4. Run the test suite +5. Submit a pull request + +## License + +[Add your license here] + +## Support + +- **Documentation**: This README +- **Issues**: [GitHub Issues](link-to-issues) +- **API Docs**: [Namecheap API](https://www.namecheap.com/support/api/intro/) | [Cloudflare API](https://developers.cloudflare.com/api/)
\ No newline at end of file |