gh-christianlouis-dmarq/docs/user_guide/deployment_guide.md

DMARQ Deployment Guide

This guide provides step-by-step instructions for deploying DMARQ in various environments.

Table of Contents

1. Docker Deployment (Recommended)
2. Manual Installation
3. Environment Configuration
4. Database Setup
5. Production Best Practices
6. Upgrading

For day-to-day production operation, use the Operator Runbook. For failure recovery, use Troubleshooting Playbooks.

Docker Deployment (Recommended)

The easiest way to deploy DMARQ is using Docker and Docker Compose. This approach packages all dependencies and provides a consistent environment.

Prerequisites

• Docker Engine 20.10.0 or later
• Docker Compose v2.0.0 or later
• 2GB RAM minimum (4GB recommended)
• 20GB storage space

Deployment Steps

1. Clone the repository

   git clone https://github.com/yourusername/dmarq.git
   cd dmarq
   

2. Configure environment variables

   Create a .env file in the project root:

   # Database Configuration
   DB_TYPE=sqlite  # or postgres for production
   DB_PATH=./data/dmarq.db  # for SQLite
   # For PostgreSQL:
   # DB_HOST=postgres
   # DB_PORT=5432
   # DB_USER=dmarq
   # DB_PASS=secure_password
   # DB_NAME=dmarq
   
   # IMAP Configuration (optional)
   IMAP_ENABLED=false
   # IMAP_SERVER=mail.example.com
   # IMAP_PORT=993
   # IMAP_USERNAME=dmarc@example.com
   # IMAP_PASSWORD=your_secure_password
   # IMAP_USE_SSL=true
   # IMAP_POLLING_INTERVAL=60
   
   # Security Settings
   SECRET_KEY=generate_a_secure_random_key
   ALLOWED_HOSTS=localhost,127.0.0.1
   

   Generate a secure random key for SECRET_KEY:

   openssl rand -hex 32
   

3. Start the containers

   docker-compose up -d
   

4. Access the application

   Open your browser and navigate to http://localhost:8000

5. Check container status

   docker-compose ps
   

Updating the Deployment

To update to a newer version:

git pull
docker-compose down
docker-compose build
docker-compose up -d

Manual Installation

For environments where Docker isn't available, you can install DMARQ manually.

Prerequisites

• Python 3.13 or higher
• pip and virtualenv
• Node.js 16+ (if modifying frontend assets)

Installation Steps

1. Set up virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

2. Install dependencies

   cd backend
   pip install -r requirements.txt
   

3. Configure environment variables

   Create a .env file in the backend directory with the same variables as in the Docker deployment.

4. Initialize the database

   cd app
   python -m alembic upgrade head
   

5. Start the application

   uvicorn main:app --host 0.0.0.0 --port 8000
   

6. Set up a production server

   For production, use a proper ASGI server like Uvicorn behind Nginx:

   # Example systemd service
   [Unit]
   Description=DMARQ Application
   After=network.target
   
   [Service]
   User=dmarq
   WorkingDirectory=/path/to/dmarq/backend/app
   ExecStart=/path/to/dmarq/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
   Restart=always
   
   [Install]
   WantedBy=multi-user.target
   

Environment Configuration

DMARQ can be configured through environment variables:

Core Settings

Variable	Description	Default
DEBUG	Enable debug mode	false
SECRET_KEY	Secret key for session security	Required
ALLOWED_HOSTS	Comma-separated list of allowed hosts	localhost,127.0.0.1

Database Settings

Variable	Description	Default
DB_TYPE	Database type (sqlite, postgres)	sqlite
DB_PATH	Path to SQLite database file	./data/dmarq.db
DB_HOST	PostgreSQL host	-
DB_PORT	PostgreSQL port	5432
DB_USER	PostgreSQL username	-
DB_PASS	PostgreSQL password	-
DB_NAME	PostgreSQL database name	-

IMAP Settings

Variable	Description	Default
IMAP_ENABLED	Enable IMAP report fetching	false
IMAP_SERVER	IMAP server address	-
IMAP_PORT	IMAP server port	993
IMAP_USERNAME	IMAP username	-
IMAP_PASSWORD	IMAP password	-
IMAP_USE_SSL	Use SSL for IMAP connection	true
IMAP_POLLING_INTERVAL	Minutes between polling	60

Database Setup

DMARQ supports SQLite (default) and PostgreSQL databases.

SQLite (Default)

SQLite is suitable for smaller deployments with fewer domains and reports. No additional configuration is required as it works out of the box.

PostgreSQL (Recommended for Production)

1. Create a PostgreSQL database and user

   CREATE USER dmarq WITH PASSWORD 'secure_password';
   CREATE DATABASE dmarq OWNER dmarq;
   

2. Update environment variables

   DB_TYPE=postgres
   DB_HOST=your_postgres_host
   DB_PORT=5432
   DB_USER=dmarq
   DB_PASS=secure_password
   DB_NAME=dmarq
   

3. Run database migrations

   cd backend/app
   python -m alembic upgrade head
   

Production Best Practices

For production deployments, consider the following:

1. Use HTTPS

   Set up SSL/TLS with a valid certificate using a reverse proxy like Nginx:

   server {
     listen 80;
     server_name dmarq.example.com;
     return 301 https://$server_name$request_uri;
   }
   
   server {
     listen 443 ssl;
     server_name dmarq.example.com;
   
     ssl_certificate /path/to/cert.pem;
     ssl_certificate_key /path/to/key.pem;
   
     location / {
       proxy_pass http://127.0.0.1:8000;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
     }
   }
   

2. Regular Backups

   Set up regular database backups:

   # For PostgreSQL
   pg_dump -U dmarq dmarq > dmarq_backup_$(date +%Y%m%d).sql
   
   # For SQLite
   sqlite3 data/dmarq.db .dump > dmarq_backup_$(date +%Y%m%d).sql
   

3. Monitoring

   Monitor the application using tools like Prometheus and Grafana.

4. Secure Credentials

   Store sensitive credentials in a secure vault rather than environment variables for production environments.

Upgrading

Major Version Upgrades

1. Backup your data

   # For PostgreSQL
   pg_dump -U dmarq dmarq > dmarq_backup_before_upgrade.sql
   
   # For SQLite
   sqlite3 data/dmarq.db .dump > dmarq_backup_before_upgrade.sql
   

2. Update the repository

   git fetch --tags
   git checkout v2.0.0  # Replace with your target version
   

3. Update dependencies

   pip install -r requirements.txt
   

4. Run database migrations

   cd backend/app
   python -m alembic upgrade head
   

5. Restart the application

   # For Docker
   docker-compose down
   docker-compose up -d
   
   # For manual installations
   sudo systemctl restart dmarq
   

Minor Version Upgrades

For minor version upgrades (e.g., 1.1.0 to 1.2.0), the process is similar but generally has less risk of breaking changes:

git fetch --tags
git checkout v1.2.0  # Replace with your target version
docker-compose down
docker-compose up -d

Always check the release notes for any specific upgrade instructions or breaking changes.