94 lines
3.9 KiB
Markdown
94 lines
3.9 KiB
Markdown
|
# mail2couch Documentation
|
||
|
|
|
||
|
|
This directory contains comprehensive documentation for the mail2couch project, which provides two production-ready implementations for backing up mail from IMAP servers to CouchDB.
|
||
|
|
|
||
|
|
## 📚 Documentation Index
|
||
|
|
|
||
|
|
### Core Documentation
|
||
|
|
- **[ANALYSIS.md](ANALYSIS.md)** - Detailed technical analysis of both implementations
|
||
|
|
- **[IMPLEMENTATION_COMPARISON.md](IMPLEMENTATION_COMPARISON.md)** - Side-by-side comparison of Go vs Rust implementations
|
||
|
|
- **[couchdb-schemas.md](couchdb-schemas.md)** - CouchDB document schemas and database structure
|
||
|
|
- **[TODO.md](TODO.md)** - Development roadmap and outstanding tasks
|
||
|
|
|
||
|
|
### Configuration & Setup
|
||
|
|
- **[FOLDER_PATTERNS.md](FOLDER_PATTERNS.md)** - Guide to folder filtering patterns and wildcards
|
||
|
|
- **[test-config-comparison.md](test-config-comparison.md)** - Configuration examples and testing scenarios
|
||
|
|
|
||
|
|
### Examples
|
||
|
|
- **[examples/](examples/)** - Sample CouchDB documents and configuration files
|
||
|
|
- `sample-mail-document.json` - Complete email document with attachments
|
||
|
|
- `sample-sync-metadata.json` - Sync state tracking document
|
||
|
|
- `simple-mail-document.json` - Basic email document structure
|
||
|
|
|
||
|
|
## 🚀 Quick Start
|
||
|
|
|
||
|
|
Both implementations are production-ready with identical feature sets:
|
||
|
|
|
||
|
|
### Go Implementation
|
||
|
|
```bash
|
||
|
|
cd go && go build -o mail2couch-go .
|
||
|
|
./mail2couch-go --config ../config.json --dry-run
|
||
|
|
```
|
||
|
|
|
||
|
|
### Rust Implementation
|
||
|
|
```bash
|
||
|
|
cd rust && cargo build --release
|
||
|
|
./target/release/mail2couch-rs --config ../config.json --dry-run
|
||
|
|
```
|
||
|
|
|
||
|
|
## ✅ Current Status (August 2025)
|
||
|
|
|
||
|
|
Both implementations are **production-ready** with:
|
||
|
|
|
||
|
|
- ✅ **Full IMAP support** with TLS/SSL connections
|
||
|
|
- ✅ **Server-side folder filtering** using IMAP LIST patterns
|
||
|
|
- ✅ **Server-side message filtering** using IMAP SEARCH with keyword support
|
||
|
|
- ✅ **Binary attachment handling** with CouchDB native attachments
|
||
|
|
- ✅ **Incremental synchronization** with metadata tracking
|
||
|
|
- ✅ **Sync vs Archive modes** for different backup strategies
|
||
|
|
- ✅ **Dry-run mode** for safe testing
|
||
|
|
- ✅ **Comprehensive error handling** with graceful fallbacks
|
||
|
|
- ✅ **SystemD integration** with timer units for automated scheduling
|
||
|
|
- ✅ **Build system integration** with justfile for unified project management
|
||
|
|
|
||
|
|
## 🔧 Key Features
|
||
|
|
|
||
|
|
### Filtering & Search
|
||
|
|
- **Folder Filtering**: Wildcard patterns (`*`, `?`, `[abc]`) with include/exclude lists
|
||
|
|
- **Message Filtering**: Subject, sender, and recipient keyword filtering
|
||
|
|
- **IMAP SEARCH**: Server-side filtering when supported, client-side fallback
|
||
|
|
- **Date Filtering**: Incremental sync based on last sync time or configured since date
|
||
|
|
|
||
|
|
### Data Storage
|
||
|
|
- **CouchDB Integration**: Native attachment storage, per-account databases
|
||
|
|
- **Document Structure**: Standardized schema with full email metadata
|
||
|
|
- **Sync Metadata**: State tracking for efficient incremental updates
|
||
|
|
- **Duplicate Prevention**: UID-based deduplication across syncs
|
||
|
|
|
||
|
|
### Operations
|
||
|
|
- **Mode Selection**: Archive (append-only) or Sync (mirror) modes
|
||
|
|
- **Connection Handling**: Automatic retry logic, graceful error recovery
|
||
|
|
- **Progress Reporting**: Detailed logging with message counts and timing
|
||
|
|
- **Resource Management**: Configurable message limits, connection pooling
|
||
|
|
|
||
|
|
## 📊 Performance & Compatibility
|
||
|
|
|
||
|
|
Both implementations have been tested with:
|
||
|
|
- **IMAP Servers**: Gmail, Office365, Dovecot, GreenMail
|
||
|
|
- **CouchDB Versions**: 3.x with native attachment support
|
||
|
|
- **Message Volumes**: Tested with thousands of messages and large attachments
|
||
|
|
- **Network Conditions**: Automatic retry and reconnection handling
|
||
|
|
|
||
|
|
## 🛠️ Development
|
||
|
|
|
||
|
|
See individual implementation directories for development setup:
|
||
|
|
- **Go**: `/go/` - Standard Go toolchain with modules
|
||
|
|
- **Rust**: `/rust/` - Cargo-based build system with comprehensive testing
|
||
|
|
|
||
|
|
For unified development commands, use the project justfile:
|
||
|
|
```bash
|
||
|
|
just build # Build both implementations
|
||
|
|
just test # Run all tests
|
||
|
|
just check # Run linting and formatting
|
||
|
|
just install # Install systemd services
|
||
|
|
```
|