mail2couch/docs/ENVIRONMENT_VARIABLES.md

# 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