mirror of
https://github.com/suitenumerique/messages.git
synced 2026-09-30 13:45:00 +02:00
Bastien Ogier
c46e2045bb
Removed the direct access grant on the rest-api client in the dev realm.json Repair make test-keycloak, which could not run against a freshly imported realm. The fixtures need more rights than the rest-api service account holds, so they now use the bootstrap admin service account. The bootstrap admin user cannot serve here, because it has an empty profile and Keycloak refuses the password grant. Grant view-realm to the service account. set_realm_role reads a realm role by id, which fails with 403 without that role. Add a setup guide for the authentication provider and one for the identity provider. Document the required client shape in env.md.
263 lines
8.5 KiB
Markdown
263 lines
8.5 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`
|
|
- See the [identity provider guide](./identity-provider.md) to create the realm and the clients
|
|
|
|
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
|
|
- A mail domain with `oidc_autojoin` gives each user a mailbox at login. This needs no `IDENTITY_PROVIDER`.
|
|
- A mail domain with `identity_sync` pushes each mailbox to Keycloak. See the [identity provider guide](./identity-provider.md)
|
|
|
|
### 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)!
|