🚀 CalPlaneBot - Advanced Plane ↔ CalDAV Integration Service for Task Management
Automatically synchronize Plane project management tasks with CalDAV-compatible calendars (Nextcloud, Baïkal, Radicale). Real-time bidirectional task sync, webhook integration, and calendar management for seamless project planning.
- Real-time bidirectional task sync between Plane and CalDAV calendars
- Automatic task creation, updates, and status synchronization
- Intelligent conflict resolution and data consistency
- Instant webhook-triggered updates from Plane API
- Event-driven synchronization for immediate task changes
- Reliable webhook payload processing and error handling
- Automatic calendar creation and organization per Plane project
- Hierarchical calendar structure with project categorization
- Calendar permissions and access control management
- Complete label, priority, and assignee information preservation
- Custom field mapping between Plane and calendar events
- Task description, due dates, and status indicators
- Configurable synchronization intervals and batch processing
- Background job scheduling with retry mechanisms
- Time-zone aware task and calendar management
- Docker containerization with optimized images
- Docker Compose orchestration for multi-service setup
- Environment-based configuration and secrets management
- Python: Version 3.11 or higher for optimal performance
- Plane Access: Valid API credentials for Plane.so instance
- CalDAV Server: Compatible CalDAV server (Nextcloud Calendar, Baïkal, Radicale, or any CalDAV-compliant calendar server)
- Authentication: Digest or Basic authentication support for secure CalDAV connections
- Operating Systems: Linux, macOS, Windows (via Docker)
- Container Runtime: Docker Engine 20.10+ for containerized deployment
- Database: SQLite (default) or PostgreSQL for production deployments
Comprehensive testing suite for CalDAV server connectivity and authentication:
# Automated testing with environment configuration
./test-caldav.sh
# Direct Python authentication testing
python test_caldav_auth.py
# Manual testing with custom parameters
./test-caldav.sh digest https://your-caldav-server.com/caldav username passwordTest Coverage Includes:
- ✅ Authentication Validation: Digest/Basic auth testing and credential verification
- ✅ Server Compatibility: CalDAV protocol compliance and feature detection
- ✅ Resource Access: Principal discovery and calendar home set validation
- ✅ Permissions Testing: Read/write access verification for calendar operations
- ✅ SSL/TLS Security: Certificate validation and secure connection testing
- ✅ Performance Metrics: Connection timeouts and response time monitoring
Complete system health check and troubleshooting toolkit:
# Full system diagnostic suite
docker exec calplanebot_calplanebot_1 python /app/manage.py diagnosticsExpected Diagnostic Output:
============================================================
Comprehensive System Diagnostic Report
============================================================
CalDAV Connection: ✓ OK - Server responding, authentication successful
Plane API Access: ✓ OK - API endpoints accessible, token valid
Database Status: ✓ OK - Schema current, migrations applied
Service Health: ✓ OK - All services running, background jobs active
Webhook Processing: ✓ OK - Event queue processing, no backlog
✓ All systems operational - Ready for production use!
# Run comprehensive performance benchmarks
python -m pytest tests/test_stress.py -v
# Edge case and error handling validation
python -m pytest tests/test_edge_cases.py -vFast, secure, and scalable containerized deployment:
# Clone the Plane CalDAV integration repository
git clone <repository-url>
cd CalPlaneBot
# Configure environment variables for Plane and CalDAV
cp env.example .env
# Edit .env with your Plane API credentials and CalDAV server details
# Launch the synchronization service
docker-compose up -dService Access: Available at http://localhost:8765 with full API documentation at /docs
For development, testing, or custom deployments:
# Install Python dependencies and requirements
pip install -r requirements.txt
# Configure environment variables
cp env.example .env
# Edit .env file with your configuration settings
# Start the FastAPI application server
python -m uvicorn app.main:app --host 0.0.0.0 --port 8765 --reloadBefore starting, ensure you have:
- ✅ Plane API Token: Generated from your Plane workspace settings
- ✅ CalDAV Credentials: Username/password for your CalDAV server
- ✅ CalDAV URL: Full URL to your calendar server endpoint
- ✅ Environment Variables: Properly configured
.envfile - ✅ Network Access: Service can reach both Plane API and CalDAV server
Comprehensive documentation suite covering all aspects of Plane CalDAV integration:
- 📖 User Guide - Complete usage manual and workflow documentation
- ⚙️ Installation Guide - Detailed setup instructions and deployment options
- 🛠️ Administration Guide - Service management, monitoring, and maintenance procedures
- 🔧 Troubleshooting Guide - Common issues, error resolution, and debugging techniques
- 🔌 API Reference - Complete REST API specification and endpoint documentation
- 🏗️ System Architecture - Technical design, data flow diagrams, and system components
- 🏛️ Architecture Overview - System design and component interactions
- 🔄 Data Flow Documentation - Synchronization logic and data processing
- 🔗 Integration Details - Plane API and CalDAV protocol integration specifics
- 📋 Setup Verification Checklist - Pre-deployment validation steps
- 🔧 Management Commands Reference - CLI tools and administrative functions
- 🐛 Common Issues & Solutions - Problem resolution guide
- 📊 Interactive API Documentation - Live Swagger/OpenAPI documentation (when service is running)
- 🌐 Health Check Endpoint - Service status and diagnostic information
We welcome contributions to improve the Plane to CalDAV synchronization service! Here's how to get involved:
- Fork the CalPlaneBot repository on GitHub
- Clone your fork locally:
git clone https://github.com/your-username/CalPlaneBot.git - Create a feature branch:
git checkout -b feature/amazing-plane-caldav-enhancement - Develop and test your changes following our testing guidelines
- Commit with descriptive messages:
git commit -m 'Add amazing CalDAV sync enhancement' - Push to your branch:
git push origin feature/amazing-plane-caldav-enhancement - Submit a Pull Request with detailed description of your changes
- All new features must include comprehensive test coverage
- Run the full test suite:
./run_tests.sh - Ensure all CalDAV and Plane API integrations are properly tested
- Docker container builds must pass validation
- Core Synchronization Logic: Improve task sync algorithms and conflict resolution
- CalDAV Protocol Support: Add support for additional CalDAV servers and features
- Plane API Integration: Enhance webhook handling and API coverage
- Documentation: Improve user guides and technical documentation
- Performance Optimization: Database queries, caching, and background job processing
This project is licensed under the MIT License - see the LICENSE file for complete licensing details. The MIT license allows for free use, modification, and distribution of this Plane CalDAV integration service.
- 📋 GitHub Issues: Report bugs, request features, and ask questions at Issues
- 📖 Documentation: Comprehensive guides in the
docs/directory - 🔧 API Docs: Interactive API documentation at
/docswhen service is running - 🐛 Troubleshooting: Check the Troubleshooting Guide for common issues
- 📚 Documentation Hub: Complete user and developer documentation
- 🔍 Health Monitoring: Service health endpoint at
/healthfor status checks - 📊 System Diagnostics: Built-in diagnostic tools for troubleshooting
- 🐳 Docker Support: Containerized deployment for easy setup and scaling
- Current Version: Beta release with production-ready features
- Production Ready: Recommended for development and testing environments
- Roadmap: Enhanced webhook reliability, additional CalDAV server support, advanced filtering options