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>
This commit is contained in:
parent
d3d104ee71
commit
8764b44a05
9 changed files with 532 additions and 13 deletions
176
docs/ENVIRONMENT_VARIABLES.md
Normal file
176
docs/ENVIRONMENT_VARIABLES.md
Normal file
|
|
@ -0,0 +1,176 @@
|
|||
# Environment Variables Reference
|
||||
|
||||
mail2couch supports environment variable overrides for sensitive credentials, allowing you to keep passwords and usernames out of configuration files while maintaining security and flexibility.
|
||||
|
||||
## Overview
|
||||
|
||||
Environment variables take precedence over values specified in configuration files, enabling:
|
||||
- ✅ Secure credential management without plaintext passwords in config files
|
||||
- ✅ Different credentials per environment (development, staging, production)
|
||||
- ✅ Integration with CI/CD systems and secret management tools
|
||||
- ✅ SystemD service configuration with secure credential injection
|
||||
|
||||
## Supported Environment Variables
|
||||
|
||||
| Variable | Purpose | Example Value |
|
||||
|----------|---------|---------------|
|
||||
| `MAIL2COUCH_COUCHDB_USER` | Override CouchDB username | `admin` |
|
||||
| `MAIL2COUCH_COUCHDB_PASSWORD` | Override CouchDB password | `secure_password123` |
|
||||
| `MAIL2COUCH_IMAP_<NAME>_USER` | Override IMAP username for source `<NAME>` | `user@gmail.com` |
|
||||
| `MAIL2COUCH_IMAP_<NAME>_PASSWORD` | Override IMAP password for source `<NAME>` | `app_specific_password` |
|
||||
|
||||
## Name Normalization
|
||||
|
||||
The `<NAME>` portion of IMAP environment variables corresponds to your mail source name from the configuration file, normalized according to these rules:
|
||||
|
||||
1. **Convert to uppercase**: `Personal Gmail` → `PERSONAL GMAIL`
|
||||
2. **Replace non-alphanumeric characters with underscores**: `PERSONAL GMAIL` → `PERSONAL_GMAIL`
|
||||
3. **Clean up consecutive underscores**: `WORK__EMAIL` → `WORK_EMAIL`
|
||||
|
||||
### Examples
|
||||
|
||||
| Configuration Source Name | Environment Variable Prefix |
|
||||
|---------------------------|------------------------------|
|
||||
| `"Personal Gmail"` | `MAIL2COUCH_IMAP_PERSONAL_GMAIL_` |
|
||||
| `"Work Email"` | `MAIL2COUCH_IMAP_WORK_EMAIL_` |
|
||||
| `"Self-Hosted Mail"` | `MAIL2COUCH_IMAP_SELF_HOSTED_MAIL_` |
|
||||
| `"Company.com Account"` | `MAIL2COUCH_IMAP_COMPANY_COM_ACCOUNT_` |
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Override
|
||||
```bash
|
||||
# Override CouchDB password
|
||||
export MAIL2COUCH_COUCHDB_PASSWORD="secure_password"
|
||||
./mail2couch
|
||||
|
||||
# Override specific IMAP account credentials
|
||||
export MAIL2COUCH_IMAP_PERSONAL_GMAIL_PASSWORD="app_password_123"
|
||||
./mail2couch --config my-config.json
|
||||
```
|
||||
|
||||
### Multiple Account Setup
|
||||
```bash
|
||||
# Set credentials for multiple accounts
|
||||
export MAIL2COUCH_COUCHDB_USER="backup_user"
|
||||
export MAIL2COUCH_COUCHDB_PASSWORD="backup_password"
|
||||
export MAIL2COUCH_IMAP_WORK_EMAIL_USER="work@company.com"
|
||||
export MAIL2COUCH_IMAP_WORK_EMAIL_PASSWORD="work_app_password"
|
||||
export MAIL2COUCH_IMAP_PERSONAL_GMAIL_PASSWORD="gmail_app_password"
|
||||
|
||||
./mail2couch --max-messages 1000
|
||||
```
|
||||
|
||||
### SystemD Service Configuration
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Mail2Couch Email Backup
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
User=mail2couch
|
||||
Environment="MAIL2COUCH_COUCHDB_PASSWORD=secure_password"
|
||||
Environment="MAIL2COUCH_IMAP_PERSONAL_GMAIL_PASSWORD=gmail_app_pass"
|
||||
Environment="MAIL2COUCH_IMAP_WORK_EMAIL_PASSWORD=work_app_pass"
|
||||
ExecStart=/usr/local/bin/mail2couch
|
||||
WorkingDirectory=/home/mail2couch
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Docker/Container Usage
|
||||
```bash
|
||||
# Docker run with environment variables
|
||||
docker run -e MAIL2COUCH_COUCHDB_PASSWORD=secret \
|
||||
-e MAIL2COUCH_IMAP_GMAIL_PASSWORD=app_pass \
|
||||
-v /path/to/config.json:/config.json \
|
||||
mail2couch --config /config.json
|
||||
|
||||
# Docker Compose
|
||||
version: '3.8'
|
||||
services:
|
||||
mail2couch:
|
||||
image: mail2couch:latest
|
||||
environment:
|
||||
- MAIL2COUCH_COUCHDB_PASSWORD=${COUCHDB_PASSWORD}
|
||||
- MAIL2COUCH_IMAP_GMAIL_PASSWORD=${GMAIL_APP_PASSWORD}
|
||||
volumes:
|
||||
- ./config.json:/config.json
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Run Mail2Couch Backup
|
||||
run: ./mail2couch --dry-run
|
||||
env:
|
||||
MAIL2COUCH_COUCHDB_PASSWORD: ${{ secrets.COUCHDB_PASSWORD }}
|
||||
MAIL2COUCH_IMAP_GMAIL_PASSWORD: ${{ secrets.GMAIL_APP_PASSWORD }}
|
||||
```
|
||||
|
||||
## Configuration File Template
|
||||
|
||||
When using environment variables, you can use placeholder values in your configuration file:
|
||||
|
||||
```json
|
||||
{
|
||||
"couchDb": {
|
||||
"url": "https://couchdb.example.com:5984",
|
||||
"user": "placeholder_will_be_overridden",
|
||||
"password": "placeholder_will_be_overridden"
|
||||
},
|
||||
"mailSources": [
|
||||
{
|
||||
"name": "Personal Gmail",
|
||||
"enabled": true,
|
||||
"protocol": "imap",
|
||||
"host": "imap.gmail.com",
|
||||
"port": 993,
|
||||
"user": "placeholder_will_be_overridden",
|
||||
"password": "placeholder_will_be_overridden",
|
||||
"mode": "archive"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
mail2couch will show which environment variable overrides are active during startup:
|
||||
|
||||
```
|
||||
Using configuration file: config.json
|
||||
Active environment variable overrides: MAIL2COUCH_COUCHDB_PASSWORD, MAIL2COUCH_IMAP_PERSONAL_GMAIL_PASSWORD
|
||||
```
|
||||
|
||||
This helps you verify that your environment variables are being detected and applied correctly.
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Never commit real credentials to version control** - Use placeholder values in config files
|
||||
2. **Use app-specific passwords** - For Gmail, Outlook, and other providers that support them
|
||||
3. **Restrict environment variable access** - Ensure only authorized users/processes can read the environment variables
|
||||
4. **Rotate credentials regularly** - Update both app passwords and environment variable values periodically
|
||||
5. **Use secret management systems** - In production, integrate with tools like HashiCorp Vault, AWS Secrets Manager, etc.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Environment Variables Not Working
|
||||
- Check variable names match exactly (case-sensitive)
|
||||
- Verify the source name normalization (see examples above)
|
||||
- Ensure variables are exported in your shell session
|
||||
- Check for typos in variable names
|
||||
|
||||
### SystemD Service Issues
|
||||
- Verify Environment lines in service file are correct
|
||||
- Check service status: `systemctl status mail2couch`
|
||||
- View logs: `journalctl -u mail2couch -f`
|
||||
- Test manually first: `sudo -u mail2couch mail2couch --dry-run`
|
||||
|
||||
### Verification Steps
|
||||
1. Run with `--dry-run` to test without making changes
|
||||
2. Check startup output for "Active environment variable overrides"
|
||||
3. Verify authentication errors are resolved
|
||||
4. Test with minimal configuration first
|
||||
Loading…
Add table
Add a link
Reference in a new issue