Ole-Morten Duesund 8764b44a05 feat: implement comprehensive environment variable credential support

- Add environment variable overrides for sensitive credentials in both Go and Rust implementations
- Support MAIL2COUCH_COUCHDB_USER and MAIL2COUCH_COUCHDB_PASSWORD for CouchDB credentials
- Support MAIL2COUCH_IMAP_<NAME>_USER and MAIL2COUCH_IMAP_<NAME>_PASSWORD for IMAP credentials
- Implement automatic name normalization for mail source names to environment variable format
- Add runtime display of active environment variable overrides
- Enhance --help output in both implementations with comprehensive environment variable documentation
- Add detailed environment variable section to README with usage examples and security benefits
- Create comprehensive ENVIRONMENT_VARIABLES.md reference guide with SystemD, Docker, and CI/CD examples
- Update all documentation indices and cross-references
- Include security best practices and troubleshooting guidance
- Maintain full backward compatibility with existing configuration files

This enhancement addresses the high-priority security requirement to eliminate plaintext
passwords from configuration files while providing production-ready credential management
for both development and deployment scenarios.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-07 15:09:34 +02:00

4.1 KiB

Raw Blame History

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 - Detailed technical analysis of both implementations
IMPLEMENTATION_COMPARISON.md - Side-by-side comparison of Go vs Rust implementations
couchdb-schemas.md - CouchDB document schemas and database structure
TODO.md - Development roadmap and outstanding tasks

Configuration & Setup

ENVIRONMENT_VARIABLES.md - Complete guide to environment variable credential overrides
FOLDER_PATTERNS.md - Guide to folder filtering patterns and wildcards
test-config-comparison.md - Configuration examples and testing scenarios

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

cd go && go build -o mail2couch-go .
./mail2couch-go --config ../config.json --dry-run

Rust Implementation

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:

just build    # Build both implementations
just test     # Run all tests
just check    # Run linting and formatting
just install  # Install systemd services

4.1 KiB Raw Blame History