{"id":31797108,"url":"https://github.com/forwardemail/hosted-snappymail","last_synced_at":"2025-10-10T20:55:55.447Z","repository":{"id":317353731,"uuid":"1061331289","full_name":"forwardemail/hosted-snappymail","owner":"forwardemail","description":"A self hosted and forward email themed snappymail setup","archived":false,"fork":false,"pushed_at":"2025-09-30T02:47:01.000Z","size":6518,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-30T11:49:55.114Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/forwardemail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-21T17:43:10.000Z","updated_at":"2025-09-30T02:47:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"d5526ac0-ec47-4854-949e-7ad8461ab7a8","html_url":"https://github.com/forwardemail/hosted-snappymail","commit_stats":null,"previous_names":["forwardemail/hosted-snappymail"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/forwardemail/hosted-snappymail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forwardemail%2Fhosted-snappymail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forwardemail%2Fhosted-snappymail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forwardemail%2Fhosted-snappymail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forwardemail%2Fhosted-snappymail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forwardemail","download_url":"https://codeload.github.com/forwardemail/hosted-snappymail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forwardemail%2Fhosted-snappymail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005220,"owners_count":26083866,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T20:55:50.142Z","updated_at":"2025-10-10T20:55:55.435Z","avatar_url":"https://github.com/forwardemail.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ForwardEmail SnappyMail Integration\n\nThis repository contains a customized SnappyMail webmail client deployment configured for ForwardEmail's privacy-focused email hosting service.\n\n## Overview\n\nSnappyMail is a modern, lightweight web-based email client. This deployment has been customized with ForwardEmail branding, pre-configured IMAP/SMTP settings, and enhanced privacy features including zero persistent user data storage.\n\n## Quick Start\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Port 8080 available on host machine\n\n### Running the Application\n\n```bash\n# Start the container\ndocker-compose -f docker-compose-webmail.yml up -d\n\n# Access the webmail interface\nopen http://localhost:8080\n\n# Access the admin panel\nopen http://localhost:8080/?admin\n\n# Get the auto-generated admin password\ndocker exec snappymail cat /tmp/snappymail-data/_data_/_default_/admin_password.txt\n```\n\n### Default Credentials\n\n- **Admin Username**: `admin`\n- **Admin Password**: Auto-generated on first startup (see command above)\n\n## Key Differences from Default SnappyMail\n\n### 1. Branding \u0026 Theme\n\n| Setting | Default SnappyMail | ForwardEmail Configuration |\n|---------|-------------------|---------------------------|\n| **Application Title** | \"SnappyMail Webmail\" | \"ForwardEmail Webmail\" |\n| **Loading Text** | \"SnappyMail\" | \"ForwardEmail - Privacy-focused email hosting\" |\n| **Default Theme** | Default | ForwardEmail (NextcloudV25+ style) |\n| **Theme Selection** | Enabled | Disabled (locked to ForwardEmail theme) |\n\n### 2. Data Storage \u0026 Privacy\n\n| Feature | Default SnappyMail | ForwardEmail Configuration |\n|---------|-------------------|---------------------------|\n| **Data Directory** | Persistent volume | tmpfs (RAM-only, 100MB limit) |\n| **File-based Caching** | Enabled | Disabled |\n| **UID Caching** | Enabled | Disabled |\n| **System Data Cache** | Enabled | Disabled |\n| **Local Contacts** | SQLite database | Disabled |\n| **Data Persistence** | Survives restarts | Cleared on every restart |\n| **Data Location** | `/var/www/html/data` | `/tmp/snappymail-data` (tmpfs) |\n\n**Privacy Benefits:**\n- ✅ No user data written to disk\n- ✅ No email content cached locally\n- ✅ All data cleared on container restart\n- ✅ Configuration regenerated from environment/templates\n\n### 3. IMAP/SMTP Configuration\n\n**Pre-configured ForwardEmail Domain** (`forwardemail.net.json`):\n\n| Service | Default | ForwardEmail Configuration |\n|---------|---------|---------------------------|\n| **IMAP Host** | localhost | imap.forwardemail.net |\n| **IMAP Port** | 143 (STARTTLS) | 993 (SSL/TLS) |\n| **IMAP Encryption** | STARTTLS | SSL/TLS (type=2) |\n| **SMTP Host** | localhost | smtp.forwardemail.net |\n| **SMTP Port** | 25 (Plain) | 465 (SSL/TLS) |\n| **SMTP Encryption** | None | SSL/TLS (type=2) |\n| **SMTP Auth** | Disabled | Enabled |\n| **SSL Verification** | Disabled | Enabled |\n\nUsers with `@forwardemail.net` email addresses automatically use these settings.\n\n### 4. Configuration Management\n\n| Aspect | Default SnappyMail | ForwardEmail Configuration |\n|--------|-------------------|---------------------------|\n| **Config Location** | `data/_data_/_default_/configs/` | Same, but in tmpfs |\n| **Config Persistence** | Saved between restarts | Regenerated on startup |\n| **Admin Password** | Set via UI or environment | Auto-generated to tmpfs on first access |\n| **Customization** | Manual via admin panel | Automated via entrypoint script |\n\n### 5. Docker Setup\n\n| Component | Default | ForwardEmail Configuration |\n|-----------|---------|---------------------------|\n| **Base Image** | php:8.2-apache | php:8.2-apache |\n| **Data Volume** | Named volume `webmail-data` | tmpfs mount (no volume) |\n| **Entrypoint** | `apache2-foreground` | Custom `docker-entrypoint.sh` |\n| **Config Application** | Manual | Automatic on startup |\n| **Volume Mounts** | Code + persistent data | Code only (read-write) |\n\n## Architecture\n\n### File Structure\n\n```\nhosted-snappymail/\n├── docker-compose-webmail.yml    # Docker Compose configuration\n├── README.md                      # This file\n└── webmail/\n    ├── Dockerfile                 # Container build instructions\n    ├── docker-entrypoint.sh       # Startup script (applies ForwardEmail config)\n    ├── _include.php               # ForwardEmail integration config (template)\n    ├── include.php                # Active integration config\n    ├── forwardemail-config.php    # Theme and branding settings (legacy)\n    ├── forwardemail.net.json      # IMAP/SMTP defaults for ForwardEmail\n    ├── index.php                  # Application entry point\n    ├── CONFIG.md                  # Detailed configuration reference\n    ├── CONTRIBUTING.md            # Codebase overview for contributors\n    └── snappymail/                # SnappyMail v2.38.2 core\n        └── v/2.38.2/\n            ├── app/               # PHP backend\n            ├── static/            # Frontend assets (JS, CSS)\n            └── themes/\n                └── ForwardEmail/  # Custom ForwardEmail theme\n```\n\n### Startup Flow\n\n1. **Container Start**: Docker starts with custom entrypoint\n2. **Apache Launch**: Apache server starts in background\n3. **Config Monitor**: Entrypoint waits for SnappyMail setup to complete\n4. **Auto-Configuration**:\n   - Detects when `admin_password.txt` is created\n   - Updates `application.ini` with ForwardEmail branding\n   - Copies `forwardemail.net.json` domain configuration\n5. **Ready**: Webmail accessible with ForwardEmail branding\n\n### Data Flow\n\n```\nUser Request → Apache → index.php → include.php (_include.php)\n                                        ↓\n                        Sets APP_DATA_FOLDER_PATH=/tmp/snappymail-data/\n                                        ↓\n                        SnappyMail Core (v/2.38.2/include.php)\n                                        ↓\n                        Reads config from tmpfs\n                                        ↓\n                        Returns response to user\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `APP_DATA_FOLDER_PATH` | `/tmp/snappymail-data/` | Location of runtime data (in tmpfs) |\n\n## Configuration Files\n\n### `_include.php` / `include.php`\n\n**Purpose**: ForwardEmail-specific integration configuration loaded before SnappyMail initialization.\n\n**Key Settings**:\n```php\n// API Integration\ndefine('FORWARDEMAIL_API_URL', $_ENV['FORWARDEMAIL_API_URL'] ?? 'http://localhost:3000');\n\n// Data storage in tmpfs\ndefine('APP_DATA_FOLDER_PATH', $_ENV['APP_DATA_FOLDER_PATH'] ?? __DIR__ . '/data/');\n\n// Disable local storage\ndefine('APP_USE_APCU_CACHE', false);\ndefine('DISABLE_LOCAL_STORAGE', true);\n```\n\n### `docker-entrypoint.sh`\n\n**Purpose**: Automatic configuration application on container startup.\n\n**Operations**:\n1. Starts Apache in background\n2. Monitors for SnappyMail initialization\n3. Updates `application.ini` with ForwardEmail branding\n4. Installs ForwardEmail domain configuration\n5. Waits for Apache process\n\n### `forwardemail.net.json`\n\n**Purpose**: Pre-configured IMAP/SMTP settings for ForwardEmail domains.\n\n**Settings**:\n- IMAP: `imap.forwardemail.net:993` (SSL/TLS)\n- SMTP: `smtp.forwardemail.net:465` (SSL/TLS)\n- SSL verification enabled\n- SASL auth methods: PLAIN, LOGIN\n\n## Performance Considerations\n\n### Caching Disabled\n\nSince file-based caching is disabled for privacy:\n\n**Slower**:\n- No server-side caching of message lists or UIDs\n- Every request requires API calls to ForwardEmail backend\n- No persistent sessions across container restarts\n\n**Faster**:\n- RAM-based tmpfs is extremely fast (no disk I/O)\n- Browser HTTP caching still works for static assets\n- No cache invalidation overhead\n\n### Resource Usage\n\n- **RAM**: ~100MB for tmpfs data directory + normal Apache/PHP memory\n- **CPU**: Slightly higher due to no caching (more API calls)\n- **Disk**: Minimal (only code, no data)\n\n### Recommended For\n\n✅ Privacy-focused deployments where data must not touch disk\n✅ Ephemeral/stateless container architectures\n✅ API-backed systems where persistence lives in backend\n✅ Compliance requirements for zero local data retention\n\n❌ High-traffic production without API backend\n❌ Offline usage (requires ForwardEmail API)\n❌ Slow network connections to IMAP/SMTP servers\n\n## Maintenance\n\n### Viewing Logs\n\n```bash\n# Container logs\ndocker logs snappymail\n\n# Follow logs in real-time\ndocker logs -f snappymail\n\n# Check for configuration application\ndocker logs snappymail | grep -E \"Applying|Updated|Created\"\n```\n\n### Accessing Container\n\n```bash\n# Shell access\ndocker exec -it snappymail bash\n\n# Check tmpfs contents\ndocker exec snappymail ls -la /tmp/snappymail-data/\n\n# View current configuration\ndocker exec snappymail cat /tmp/snappymail-data/_data_/_default_/configs/application.ini\n```\n\n### Rebuilding\n\n```bash\n# Rebuild image\ndocker-compose -f docker-compose-webmail.yml build\n\n# Rebuild and restart (fresh tmpfs)\ndocker-compose -f docker-compose-webmail.yml down\ndocker-compose -f docker-compose-webmail.yml up -d\n```\n\n### Updating SnappyMail Version\n\n1. Update `APP_VERSION` in `webmail/_include.php`\n2. Add new version directory to `webmail/snappymail/v/X.Y.Z/`\n3. Ensure ForwardEmail theme exists in new version\n4. Test tmpfs compatibility\n5. Rebuild container\n\n## Troubleshooting\n\n### Admin Password Not Working\n\n```bash\n# Get current auto-generated password\ndocker exec snappymail cat /tmp/snappymail-data/_data_/_default_/admin_password.txt\n```\n\n### Branding Not Applied\n\n```bash\n# Check if configuration was applied\ndocker logs snappymail | grep \"Applying ForwardEmail\"\n\n# Manually verify config\ndocker exec snappymail cat /tmp/snappymail-data/_data_/_default_/configs/application.ini | grep theme\n```\n\n### Data Directory Empty\n\nThe tmpfs is cleared on every restart by design. If you need to inspect data:\n\n```bash\n# Check if tmpfs is mounted\ndocker exec snappymail mount | grep tmpfs\n\n# Check permissions\ndocker exec snappymail ls -la /tmp/snappymail-data/\n```\n\n### ForwardEmail Domain Config Missing\n\n```bash\n# Check if domain config exists\ndocker exec snappymail ls -la /tmp/snappymail-data/_data_/_default_/domains/\n\n# Manually copy if needed (requires restart)\ndocker exec snappymail cp /var/www/html/forwardemail.net.json /tmp/snappymail-data/_data_/_default_/domains/\n```\n\n## Security Considerations\n\n### Strengths\n\n- ✅ No persistent user data on disk\n- ✅ Data cleared on restart (RAM-only)\n- ✅ SSL/TLS enforced for IMAP/SMTP\n- ✅ HSTS header enabled\n- ✅ Modern PHP 8.2 with security updates\n- ✅ Auto-generated admin passwords (not in repository)\n\n### Limitations\n\n- ⚠️ Admin password stored in plain text in tmpfs (by SnappyMail design)\n- ⚠️ No persistent audit logs (cleared on restart)\n- ⚠️ Requires secure backend (ForwardEmail API)\n- ⚠️ Volume mount exposes source code to container\n\n### Recommendations\n\n1. Use strong admin passwords (change after first login)\n2. Run behind HTTPS reverse proxy (nginx, Caddy, Traefik)\n3. Restrict network access to container\n4. Monitor container logs for failed auth attempts\n5. Keep SnappyMail and base image updated\n\n## Development\n\n### Local Testing\n\n```bash\n# Build and run\ndocker-compose -f docker-compose-webmail.yml up --build\n\n# Access admin panel\nopen http://localhost:8080/?admin\n\n# Make changes to webmail/ directory (auto-reflected via volume mount)\n```\n\n### Customization\n\nTo modify ForwardEmail branding:\n\n1. **Theme**: Edit `webmail/snappymail/v/2.38.2/themes/ForwardEmail/`\n2. **Logo**: Replace `webmail/snappymail/v/2.38.2/themes/ForwardEmail/images/logo.svg`\n3. **Settings**: Modify `webmail/docker-entrypoint.sh` config application\n4. **Domain Config**: Edit `webmail/forwardemail.net.json`\n\n## Documentation\n\n- [CONFIG.md](webmail/CONFIG.md) - Detailed configuration reference\n- [CONTRIBUTING.md](webmail/CONTRIBUTING.md) - Codebase overview for contributors\n- [SnappyMail Wiki](https://github.com/the-djmaze/snappymail/wiki) - Upstream documentation\n\n## License\n\nSnappyMail is released under **GNU AGPL v3**.\nSee: http://www.gnu.org/licenses/agpl-3.0.html\n\nCopyright (c) 2020-2024 SnappyMail\nCopyright (c) 2013-2022 RainLoop\n\n## Support\n\nFor issues specific to this ForwardEmail integration:\n- Review [CONFIG.md](webmail/CONFIG.md) for configuration details\n- Check Docker logs: `docker logs snappymail`\n- Inspect tmpfs: `docker exec snappymail ls -la /tmp/snappymail-data/`\n\nFor SnappyMail core issues:\n- [SnappyMail GitHub Issues](https://github.com/the-djmaze/snappymail/issues)\n- [SnappyMail Wiki](https://github.com/the-djmaze/snappymail/wiki)\n\n## Version\n\n- **SnappyMail**: v2.38.2\n- **PHP**: 8.2\n- **Apache**: 2.4.65\n- **Configuration**: ForwardEmail Integration v1.0","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforwardemail%2Fhosted-snappymail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforwardemail%2Fhosted-snappymail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforwardemail%2Fhosted-snappymail/lists"}