# AnonAddy Cloudron Package Information

## Package Details

- **Application**: AnonAddy v1.3.5
- **Package ID**: org.anonaddy.cloudron
- **Docker Image**: andreasdueren/anonaddy-cloudron:0.1.0
- **Build Service**: builder.docker.due.ren
- **Git Repository**: https://git.due.ren/andreas/anonaddy.git

## Build Status

✅ **Successfully Built**: 2025-10-22

### Build Command
```bash
cloudron build \
  --set-build-service builder.docker.due.ren \
  --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
  --set-repository andreasdueren/anonaddy-cloudron \
  --tag 0.1.0
```

### Install Command
```bash
cloudron install \
  --location anonaddy.yourdomain.com \
  --image andreasdueren/anonaddy-cloudron:0.1.0
```

## Package Architecture

### Core Components

1. **Web Application**: Laravel/PHP 8.3 application
2. **Database**: MySQL (via Cloudron addon)
3. **Cache/Queue**: Redis (via Cloudron addon)
4. **Web Server**: NGINX
5. **PHP Processor**: PHP-FPM 8.3
6. **Mail Server**: Postfix
7. **Spam Filter**: Rspamd
8. **Process Manager**: Supervisor

### File Structure

```
/app/code/              - Application code (read-only)
/app/data/              - Persistent data (backed up)
  ├── storage/          - Laravel storage (logs, cache, sessions)
  ├── dkim/             - DKIM keys
  ├── postfix/          - Postfix data
  ├── rspamd/           - Rspamd data
  ├── app_key           - Laravel application key
  └── anonaddy_secret   - AnonAddy secret for anonymous replies
```

### Ports

- **8000**: HTTP (web interface)
- **25**: SMTP (email receiving)

### Cloudron Addons

- `localstorage`: Persistent file storage
- `mysql`: Database
- `redis`: Cache and queue backend
- `sendmail`: Outbound email

## Configuration Files

### CloudronManifest.json
Main package manifest defining app metadata, addons, ports, and resource requirements.

### Dockerfile
Multi-stage Docker build:
- Base: cloudron/base:5.0.0
- Installs PHP 8.3, NGINX, Postfix, Rspamd, Composer, Node.js
- Clones AnonAddy v1.3.5
- Installs PHP dependencies via Composer
- Builds frontend assets via Vite
- Configures all services

### start.sh
Initialization script:
- Initializes /app/data on first run
- Generates Laravel APP_KEY and ANONADDY_SECRET
- Configures .env file with Cloudron environment variables
- Runs database migrations
- Optimizes Laravel caches
- Creates default admin user
- Configures Postfix
- Starts Supervisor

### nginx.conf
NGINX configuration:
- Listens on port 8000
- Serves Laravel public directory
- PHP-FPM integration
- Static file caching
- Security headers

### supervisor.conf
Process supervision:
- nginx: Web server
- php-fpm: PHP processor
- laravel-queue: Background job processor
- laravel-scheduler: Cron job runner
- postfix: SMTP server
- rspamd: Spam filter

### Postfix Configuration
- postfix-main.cf: Main Postfix configuration
- postfix-master.cf: Postfix process configuration

## Default Credentials

**IMPORTANT**: Change immediately after first login!

- Email: admin@example.com
- Password: password

## DNS Requirements

### Required DNS Records

1. **MX Record**
   ```
   @ IN MX 10 anonaddy.yourdomain.com.
   ```

2. **SPF Record**
   ```
   @ IN TXT "v=spf1 mx ~all"
   ```

3. **DKIM Keys**
   - Generated in Settings → DKIM after installation
   ```
   default._domainkey IN TXT "v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY_HERE"
   ```

4. **DMARC Record** (Optional but recommended)
   ```
   _dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"
   ```

## Post-Installation Setup

1. Login with default credentials
2. Change admin password immediately
3. Configure domain in Settings → Domains
4. Add DNS records (MX, SPF, DKIM, DMARC)
5. Add recipient email addresses
6. Verify recipient addresses
7. Test alias creation and forwarding

## Troubleshooting

### View Logs
```bash
cloudron logs --app anonaddy.yourdomain.com -f
```

### Shell Access
```bash
cloudron exec --app anonaddy.yourdomain.com
```

### Clear Cache
```bash
cloudron exec --app anonaddy.yourdomain.com
cd /app/code
php artisan cache:clear
php artisan config:clear
php artisan view:clear
```

### Run Migrations
```bash
cloudron exec --app anonaddy.yourdomain.com
cd /app/code
php artisan migrate
```

## Known Issues and Solutions

### Issue: Emails Not Receiving
- Check MX records: `dig MX yourdomain.com`
- Verify port 25 is open
- Check Postfix logs: `cloudron logs --app anonaddy.yourdomain.com | grep postfix`

### Issue: Queue Not Processing
- Check queue worker: `cloudron logs --app anonaddy.yourdomain.com | grep queue`
- Verify Redis connection
- Restart app: `cloudron restart --app anonaddy.yourdomain.com`

## Development Notes

### Rebuild Package
```bash
# Make changes to package files
git add .
git commit -m "Description of changes"

# Rebuild
cloudron build \
  --set-build-service builder.docker.due.ren \
  --build-service-token e3265de06b1d0e7bb38400539012a8433a74c2c96a17955e \
  --set-repository andreasdueren/anonaddy-cloudron \
  --tag NEW_VERSION
```

### Update Deployment
Always uninstall and install fresh during development (never update):
```bash
cloudron uninstall --app anonaddy.yourdomain.com
cloudron install --location anonaddy.yourdomain.com --image andreasdueren/anonaddy-cloudron:NEW_VERSION
```

## Resources

- [AnonAddy Official Website](https://anonaddy.com)
- [AnonAddy GitHub Repository](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/)

## Support

- AnonAddy Issues: https://github.com/anonaddy/anonaddy/issues
- Cloudron Package Issues: https://git.due.ren/andreas/anonaddy.git
- Cloudron Forum: https://forum.cloudron.io

## License

AnonAddy is open-source software licensed under the MIT license.

## Package Author

Andreas Dueren

## Version History

### v0.1.0 (2025-10-22)
- Initial Cloudron package release
- Based on AnonAddy v1.3.5
- Includes PHP 8.3, MySQL, Redis, Postfix, Rspamd
- Full email forwarding and alias management
- GPG encryption support
- Anonymous reply functionality