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

# 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

# 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

[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

# 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

# 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:

{
  "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