mirror of
https://github.com/suitenumerique/messages.git
synced 2026-08-17 21:25:41 +02:00
Sylvain Zimmerandjbpenrath
f4d235825f
Notably, we try to reduce disk usage by standardizind on common base Docker images. We also improve node_modules by reducing duplicate dependencies and install speed.
260 lines
8.2 KiB
Markdown
260 lines
8.2 KiB
Markdown
# Self-Hosting Guide
|
|
|
|
This guide explains how to deploy Messages in production, focusing on Messages-specific configuration and architecture.
|
|
|
|
## Overview
|
|
|
|
Messages is designed to be self-hosted. See [Architecture](./architecture.md) for component details.
|
|
|
|
## Prerequisites
|
|
|
|
- **Domain name(s)** for your email service
|
|
- **SSL certificates** for your domains
|
|
- **Server resources**: Minimum 4GB RAM
|
|
|
|
## Deployment Options
|
|
|
|
Messages supports multiple deployment strategies depending on your infrastructure and expertise level:
|
|
|
|
### Docker Compose (Recommended for most users)
|
|
|
|
**Best for**: Small to medium deployments, single-server setups, quick prototyping
|
|
|
|
**Requirements**:
|
|
- Docker and Docker Compose installed
|
|
- Single server or VM with sufficient resources
|
|
- Basic Docker knowledge
|
|
|
|
**Process**:
|
|
1. Start from the `compose.yaml` in the repository
|
|
2. Create production environment files (`deploy/env/production/*.defaults`)
|
|
3. Deploy to any environment where Docker Compose runs
|
|
4. Configure DNS and SSL certificates
|
|
|
|
**Advantages**:
|
|
- Simplest setup and maintenance
|
|
- Easy to understand and modify
|
|
- Quick deployment and updates
|
|
- Good for development and testing
|
|
|
|
### Ansible Deployment
|
|
|
|
**Best for**: Multi-server deployments, infrastructure automation, production environments
|
|
|
|
**Requirements**:
|
|
- Ansible knowledge
|
|
- Target servers with Docker support
|
|
- Infrastructure automation experience
|
|
|
|
**Process**:
|
|
1. Use our [ST Ansible repository](https://github.com/suitenumerique/st-ansible) as a base
|
|
2. Customize playbooks for your infrastructure
|
|
3. Deploy across multiple servers with automation
|
|
4. Configure monitoring and backup strategies
|
|
|
|
**Advantages**:
|
|
- Infrastructure as code
|
|
- Automated deployment and updates
|
|
- Multi-server support
|
|
- Production-ready with monitoring
|
|
|
|
### Kubernetes Deployment
|
|
|
|
**Best for**: Large-scale deployments, cloud-native environments, enterprise setups
|
|
|
|
**Requirements**:
|
|
- Kubernetes cluster
|
|
- Helm knowledge (when charts become available)
|
|
- Container orchestration experience
|
|
|
|
**Process**:
|
|
1. Wait for Helm charts (coming in future releases)
|
|
2. Deploy to Kubernetes cluster
|
|
3. Configure ingress controllers and load balancers
|
|
4. Set up monitoring with Prometheus/Grafana
|
|
|
|
**Advantages**:
|
|
- High availability and scalability
|
|
- Advanced orchestration features
|
|
- Cloud-native deployment patterns
|
|
- Enterprise-grade monitoring and logging
|
|
|
|
**Note**: Kubernetes deployment might be supported in future releases with official Helm charts.
|
|
|
|
## Messages-Specific Configuration
|
|
|
|
### 1. Technical Domain Setup
|
|
|
|
Messages uses a technical domain concept for DNS infrastructure:
|
|
|
|
```bash
|
|
# Set your technical domain
|
|
MESSAGES_TECHNICAL_DOMAIN=mail.yourdomain.com
|
|
```
|
|
|
|
**Technical Domain DNS Records:**
|
|
```
|
|
mx1.mail.yourdomain.com. A YOUR_SERVER_IP
|
|
mx2.mail.yourdomain.com. A YOUR_SERVER_IP
|
|
_spf.mail.yourdomain.com. TXT "v=spf1 ip4:YOUR_SERVER_IP -all"
|
|
```
|
|
|
|
**Customer Domain DNS Records:**
|
|
```
|
|
@ MX 10 mx1.customer-domain.com.
|
|
@ MX 20 mx2.customer-domain.com.
|
|
@ TXT "v=spf1 include:_spf.mail.yourdomain.com -all"
|
|
_dmarc TXT "v=DMARC1; p=reject; adkim=s; aspf=s;"
|
|
```
|
|
|
|
The DNS records for each customer domains are available either via API at http://localhost:8901/api/v1.0/maildomains/{maildomain-uuid}/ or in the admin interface at http://localhost:8900/domain
|
|
|
|
### 2. Environment Configuration
|
|
|
|
Messages uses environment variables as the primary configuration method:
|
|
|
|
**Environment File Structure:**
|
|
- `deploy/env/production/backend.defaults` - Main Django application settings
|
|
- `deploy/env/production/frontend.defaults` - Frontend configuration
|
|
- `deploy/env/production/mta-in.defaults` - Inbound mail server settings
|
|
- `deploy/env/production/mta-out.defaults` - Outbound mail server settings
|
|
- `deploy/env/production/postgresql.defaults` - Database configuration
|
|
- `deploy/env/production/keycloak.defaults` - Identity provider settings
|
|
|
|
**For detailed environment variable documentation, see [Environment Variables](./env.md).**
|
|
|
|
### 3. MTA Configuration
|
|
|
|
#### MTA-in (Inbound Email)
|
|
- Configured via `deploy/env/production/mta-in.defaults`
|
|
- Uses custom milter for synchronous delivery during SMTP sessions
|
|
- Validates recipients via REST API before accepting messages
|
|
|
|
#### MTA-out (Outbound Email)
|
|
- Configured via `deploy/env/production/mta-out.defaults`
|
|
- Supports relay configuration for external SMTP providers
|
|
- Requires TLS certificates for production
|
|
|
|
### 4. DNS Management
|
|
|
|
Messages includes automated DNS management:
|
|
|
|
```bash
|
|
# Check DNS records for a customer domain
|
|
python manage.py dns_check --domain example.com
|
|
|
|
# Provision DNS records automatically
|
|
python manage.py dns_provision --domain example.com --provider scaleway
|
|
|
|
# Simulate provisioning without making changes
|
|
python manage.py dns_provision --domain example.com --pretend
|
|
```
|
|
|
|
**Supported DNS Providers:**
|
|
- Scaleway DNS (full automation support)
|
|
|
|
### 5. Domain and Mailbox Management
|
|
|
|
#### Creating Mail Domains
|
|
```bash
|
|
# Via Django admin at /admin/
|
|
# Via API endpoints
|
|
# Via management commands
|
|
python manage.py shell
|
|
>>> from core.models import MailDomain
|
|
>>> MailDomain.objects.create(name='customer-domain.com')
|
|
```
|
|
|
|
#### Mailbox Creation
|
|
- Manual creation through admin interface
|
|
- Automatic creation via OIDC integration
|
|
- Programmatic creation via API
|
|
|
|
### 6. Identity Management
|
|
|
|
Messages uses OpenID Connect (OIDC) for user authentication. This is the only authentication method supported.
|
|
|
|
**OIDC Configuration Options:**
|
|
|
|
1. **Bundled Keycloak** (Recommended for most deployments)
|
|
- Keycloak is included in the default Docker Compose setup
|
|
- Pre-configured with Messages realm and users
|
|
- Suitable for organizations wanting a self-hosted identity provider
|
|
- Configure via `deploy/env/production/keycloak.defaults`
|
|
|
|
2. **External OIDC Provider**
|
|
- Use any OIDC-compliant identity provider
|
|
- Examples: Auth0, Okta, Azure AD, Google Workspace
|
|
- Configure via `deploy/env/production/backend.defaults`
|
|
- Requires proper OIDC endpoint configuration
|
|
|
|
**User Management:**
|
|
- Users are created automatically when they first log in via OIDC
|
|
- Mailboxes can be created automatically based on OIDC email addresses
|
|
|
|
### 7. Production Deployment
|
|
|
|
For production deployment, create your own Docker Compose configuration based on `compose.yaml`:
|
|
|
|
**Key Considerations:**
|
|
- Use production environment files (`deploy/env/production/*.defaults`)
|
|
- Configure SSL/TLS certificates
|
|
- Set up persistent volumes for databases
|
|
- Implement proper restart policies
|
|
- Configure reverse proxy (Caddy) for SSL termination
|
|
|
|
## Security Considerations
|
|
|
|
### Messages-Specific Security
|
|
- **MDA API Secret**: Use strong, unique `MDA_API_SECRET`
|
|
- **OIDC Configuration**: Properly configure Keycloak endpoints
|
|
- **Technical Domain**: Secure DNS records for your technical domain
|
|
- **Environment Files**: Never commit production secrets
|
|
|
|
### IP Reputation Management
|
|
|
|
**Monitoring:**
|
|
- Check your server's IP reputation at [MXToolbox](https://mxtoolbox.com/blacklists.aspx)
|
|
- Monitor key blacklists: Spamhaus, Barracuda, SORBS
|
|
|
|
**Recovery from Blacklisting:**
|
|
1. Stop all outgoing email immediately
|
|
2. Check server logs for abuse indicators
|
|
3. Follow blacklist's delisting procedure
|
|
4. Implement stricter authentication and rate limiting
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Messages Issues
|
|
|
|
1. **MTA-in not receiving emails**
|
|
- Check firewall settings for port 25
|
|
- Verify DNS MX records point to your technical domain
|
|
- Check MTA-in logs for API connection issues
|
|
|
|
2. **MTA-out not sending emails**
|
|
- Verify SMTP credentials in environment files
|
|
- Check relay host configuration
|
|
- Review MTA-out logs for authentication errors
|
|
|
|
3. **DNS issues**
|
|
- Use `dns_check` command to verify records
|
|
- Ensure technical domain A records are correct
|
|
- Check DNS propagation with `dig`
|
|
|
|
4. **Authentication problems**
|
|
- Verify Keycloak configuration in environment files
|
|
- Check OIDC endpoint URLs
|
|
- Review backend logs for authentication errors
|
|
|
|
## Next Steps
|
|
|
|
After setting up your production environment:
|
|
|
|
1. **Test thoroughly** with a small group of users
|
|
2. **Monitor performance** and adjust resources as needed
|
|
3. **Set up automated backups** and monitoring
|
|
4. **Plan for scaling** as your user base grows
|
|
|
|
For additional help, join the [Matrix community](https://matrix.to/#/#messages-official:matrix.org)!
|