Initial AnonAddy Cloudron package
This commit is contained in:
Your Name
297
README.md
Normal file
297
README.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# AnonAddy Cloudron Package
|
||||
|
||||
This is a complete Cloudron package for [AnonAddy](https://anonaddy.com), an open-source anonymous email forwarding service.
|
||||
|
||||
## Features
|
||||
|
||||
- Anonymous email forwarding with unlimited aliases
|
||||
- Custom domain support
|
||||
- GPG/OpenPGP email encryption
|
||||
- Reply anonymously without revealing your real email
|
||||
- MySQL database for data storage
|
||||
- Redis for caching and queues
|
||||
- Postfix for SMTP email handling
|
||||
- Rspamd for spam filtering
|
||||
- Laravel queue worker for background jobs
|
||||
- Automatic database migrations
|
||||
|
||||
## Package Contents
|
||||
|
||||
- `CloudronManifest.json` - Cloudron package manifest
|
||||
- `Dockerfile` - Container image definition
|
||||
- `start.sh` - Initialization and startup script
|
||||
- `nginx.conf` - NGINX web server configuration
|
||||
- `supervisor.conf` - Process supervisor configuration
|
||||
- `postfix-main.cf` - Postfix main configuration
|
||||
- `postfix-master.cf` - Postfix master process configuration
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Cloudron CLI installed and configured
|
||||
2. Docker access (handled by Cloudron build service)
|
||||
3. Cloudron instance running version 7.0.0 or higher
|
||||
4. Domain with proper DNS configuration
|
||||
|
||||
## Building the Package
|
||||
|
||||
Build the package using the Cloudron build service:
|
||||
|
||||
```bash
|
||||
cloudron build \
|
||||
--set-build-service builder.docker.due.ren \
|
||||
--build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
|
||||
--set-repository andreasdueren/anonaddy-cloudron \
|
||||
--tag 0.1.0
|
||||
```
|
||||
|
||||
The build process will:
|
||||
1. Create a Docker image based on cloudron/base:5.0.0
|
||||
2. Install PHP 8.3, NGINX, Postfix, Rspamd, and other dependencies
|
||||
3. Clone AnonAddy v1.3.5 from GitHub
|
||||
4. Install Composer dependencies
|
||||
5. Build frontend assets
|
||||
6. Configure all services
|
||||
|
||||
## Installation
|
||||
|
||||
Install the package on your Cloudron instance:
|
||||
|
||||
```bash
|
||||
cloudron install \
|
||||
--location anonaddy.yourdomain.com \
|
||||
--image andreasdueren/anonaddy-cloudron:0.1.0
|
||||
```
|
||||
|
||||
Replace `anonaddy.yourdomain.com` with your desired subdomain.
|
||||
|
||||
## Post-Installation Setup
|
||||
|
||||
### 1. Initial Login
|
||||
|
||||
After installation, you'll see a post-install message with default credentials:
|
||||
|
||||
- Email: `admin@example.com`
|
||||
- Password: `password`
|
||||
|
||||
**IMPORTANT:** Change this password immediately after first login!
|
||||
|
||||
### 2. DNS Configuration
|
||||
|
||||
Configure the following DNS records for your domain:
|
||||
|
||||
#### MX Record
|
||||
```
|
||||
@ IN MX 10 anonaddy.yourdomain.com.
|
||||
```
|
||||
|
||||
#### SPF Record
|
||||
```
|
||||
@ IN TXT "v=spf1 mx ~all"
|
||||
```
|
||||
|
||||
#### DKIM Keys
|
||||
1. Login to AnonAddy
|
||||
2. Navigate to Settings → DKIM
|
||||
3. Generate DKIM keys
|
||||
4. Add the provided DNS TXT record
|
||||
|
||||
Example:
|
||||
```
|
||||
default._domainkey IN TXT "v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY_HERE"
|
||||
```
|
||||
|
||||
#### DMARC Record (Optional but recommended)
|
||||
```
|
||||
_dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"
|
||||
```
|
||||
|
||||
### 3. Configure Domain Settings
|
||||
|
||||
1. Login to AnonAddy
|
||||
2. Go to Settings → Domains
|
||||
3. Add your custom domain(s)
|
||||
4. Verify domain ownership
|
||||
|
||||
### 4. Configure Email Recipients
|
||||
|
||||
1. Add recipient email addresses (your real email addresses)
|
||||
2. Verify recipient addresses via email confirmation
|
||||
3. Set default recipient for new aliases
|
||||
|
||||
## Usage
|
||||
|
||||
### Creating Aliases
|
||||
|
||||
AnonAddy supports multiple alias formats:
|
||||
|
||||
1. **Standard Aliases:** `anything@yourdomain.com`
|
||||
2. **UUID Aliases:** `94960540-f914-42e0-9c50-6fecbe7f5061@yourdomain.com`
|
||||
3. **Custom Aliases:** `newsletter@yourdomain.com`
|
||||
|
||||
### Replying Anonymously
|
||||
|
||||
Reply to forwarded emails directly. AnonAddy will send the reply through the alias, maintaining your anonymity.
|
||||
|
||||
### Encryption
|
||||
|
||||
Enable GPG encryption in Settings to encrypt all incoming emails with your public key.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Services
|
||||
|
||||
The package runs multiple services via supervisor:
|
||||
|
||||
- **NGINX** - Web server (port 8000)
|
||||
- **PHP-FPM** - PHP processor
|
||||
- **Laravel Queue Worker** - Background job processing
|
||||
- **Laravel Scheduler** - Cron job handler
|
||||
- **Postfix** - SMTP server (port 25)
|
||||
- **Rspamd** - Spam filtering (port 11334)
|
||||
|
||||
### Data Persistence
|
||||
|
||||
All persistent data is stored in `/app/data`:
|
||||
|
||||
- `/app/data/storage` - Laravel storage (logs, cache, sessions)
|
||||
- `/app/data/dkim` - DKIM keys
|
||||
- `/app/data/postfix` - Postfix spool
|
||||
- `/app/data/rspamd` - Rspamd data
|
||||
- `/app/data/app_key` - Laravel application key
|
||||
- `/app/data/anonaddy_secret` - AnonAddy secret for anonymous replies
|
||||
|
||||
### Database
|
||||
|
||||
The package uses:
|
||||
- **MySQL** - Main database (via Cloudron addon)
|
||||
- **Redis** - Cache and queue backend (via Cloudron addon)
|
||||
|
||||
### Email Integration
|
||||
|
||||
- **Inbound:** Postfix receives emails on port 25
|
||||
- **Outbound:** Cloudron SMTP addon for sending emails
|
||||
- **Spam Filtering:** Rspamd filters incoming emails
|
||||
- **Virtual Aliases:** Postfix queries Rspamd for alias lookups
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
cloudron logs --app anonaddy.yourdomain.com -f
|
||||
```
|
||||
|
||||
### Shell Access
|
||||
|
||||
```bash
|
||||
cloudron exec --app anonaddy.yourdomain.com
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Emails Not Receiving
|
||||
|
||||
1. Check MX records: `dig MX yourdomain.com`
|
||||
2. Verify port 25 is open on your Cloudron server
|
||||
3. Check Postfix logs: `cloudron logs --app anonaddy.yourdomain.com | grep postfix`
|
||||
4. Test SMTP: `telnet anonaddy.yourdomain.com 25`
|
||||
|
||||
#### Emails Marked as Spam
|
||||
|
||||
1. Ensure SPF record is configured
|
||||
2. Add DKIM keys in Settings
|
||||
3. Configure DMARC record
|
||||
4. Check your server's IP reputation
|
||||
|
||||
#### Queue Not Processing
|
||||
|
||||
1. Check Laravel queue worker: `cloudron logs --app anonaddy.yourdomain.com | grep queue`
|
||||
2. Verify Redis connection
|
||||
3. Restart the app: `cloudron restart --app anonaddy.yourdomain.com`
|
||||
|
||||
#### Application Errors
|
||||
|
||||
1. Check storage permissions in `/app/data/storage`
|
||||
2. Clear cache: `cloudron exec --app anonaddy.yourdomain.com 'php artisan cache:clear'`
|
||||
3. Run migrations: `cloudron exec --app anonaddy.yourdomain.com 'php artisan migrate'`
|
||||
|
||||
### Database Migrations
|
||||
|
||||
Migrations run automatically on startup. To manually run migrations:
|
||||
|
||||
```bash
|
||||
cloudron exec --app anonaddy.yourdomain.com
|
||||
cd /app/code
|
||||
php artisan migrate
|
||||
```
|
||||
|
||||
### Clear Cache
|
||||
|
||||
```bash
|
||||
cloudron exec --app anonaddy.yourdomain.com
|
||||
cd /app/code
|
||||
php artisan cache:clear
|
||||
php artisan config:clear
|
||||
php artisan view:clear
|
||||
```
|
||||
|
||||
## Updating
|
||||
|
||||
To update to a new version:
|
||||
|
||||
1. Build the new version with updated tag
|
||||
2. Uninstall the old version: `cloudron uninstall --app anonaddy.yourdomain.com`
|
||||
3. Install the new version: `cloudron install --location anonaddy.yourdomain.com --image andreasdueren/anonaddy-cloudron:NEW_VERSION`
|
||||
|
||||
**Note:** Always backup your data before updating!
|
||||
|
||||
## Development
|
||||
|
||||
### Local Testing
|
||||
|
||||
1. Clone the repository
|
||||
2. Make changes to configuration files
|
||||
3. Build locally: `cloudron build --tag test`
|
||||
4. Install for testing: `cloudron install --location test.anonaddy.local --image andreasdueren/anonaddy-cloudron:test`
|
||||
|
||||
### File Locations
|
||||
|
||||
- Application code: `/app/code`
|
||||
- Persistent data: `/app/data`
|
||||
- NGINX config: `/etc/nginx/sites-available/default`
|
||||
- PHP-FPM config: `/etc/php/8.3/fpm/pool.d/www.conf`
|
||||
- Postfix config: `/etc/postfix/main.cf`
|
||||
- Supervisor config: `/etc/supervisor/conf.d/anonaddy.conf`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Change Default Password:** Immediately after installation
|
||||
2. **HTTPS Only:** Cloudron automatically provides SSL/TLS
|
||||
3. **SPF/DKIM/DMARC:** Configure all email authentication records
|
||||
4. **Firewall:** Ensure only necessary ports (80, 443, 25) are open
|
||||
5. **Updates:** Keep AnonAddy updated to latest version
|
||||
6. **Backups:** Regular backups via Cloudron
|
||||
|
||||
## Resources
|
||||
|
||||
- [AnonAddy Website](https://anonaddy.com)
|
||||
- [AnonAddy GitHub](https://github.com/anonaddy/anonaddy)
|
||||
- [AnonAddy Documentation](https://anonaddy.com/help)
|
||||
- [Cloudron Documentation](https://docs.cloudron.io)
|
||||
- [Cloudron Packaging Guide](https://docs.cloudron.io/packaging/)
|
||||
|
||||
## License
|
||||
|
||||
AnonAddy is open-source software licensed under the MIT license.
|
||||
|
||||
## Support
|
||||
|
||||
For issues with:
|
||||
- **AnonAddy application:** https://github.com/anonaddy/anonaddy/issues
|
||||
- **Cloudron package:** https://git.due.ren/andreas/anonaddy.git
|
||||
- **Cloudron platform:** https://forum.cloudron.io
|
||||
|
||||
## Credits
|
||||
|
||||
- AnonAddy by [Will Browning](https://github.com/willbrowningme)
|
||||
- Cloudron package by Andreas Dueren
|
||||
Reference in New Issue
Block a user