Installation Guide

Mail-Rulez can be installed using Docker (recommended) or manually. This guide covers both methods and helps you get up and running quickly.

Prerequisites

System Requirements

• Operating System: Linux, macOS, or Windows (with Docker)
• RAM: Minimum 512MB, recommended 1GB+
• Storage: 100MB for application + space for logs and data
• Network: Internet connection for IMAP access

Software Requirements

• For Docker Installation: Docker 20.10+ and Docker Compose
• For Manual Installation: Python 3.9+, pip

Docker Installation (Recommended)

Docker provides the easiest and most reliable way to run Mail-Rulez.

Quick Start

# Pull and run with Docker
docker run -d \
  --name mail-rulez \
  -p 5001:5001 \
  -v mail_rulez_data:/app/data \
  -v mail_rulez_logs:/app/logs \
  ghcr.io/real-pm/mail-rulez:latest

Using Docker Compose

1. Download the docker-compose file:

curl -O https://raw.githubusercontent.com/Real-PM/mail-rulez-public/main/docker/docker-compose.yml

2. Start the application:

docker-compose up -d

3. Verify it's running:

docker ps
# Should show mail-rulez container as "healthy"

Screenshot: Docker container running successfully

Environment Configuration

Create a .env file to customize your deployment:

# Port configuration
PORT=5001

# Logging
LOG_LEVEL=INFO

# Security (auto-generated if not provided)
MASTER_KEY=your-secure-master-key
FLASK_SECRET_KEY=your-secure-flask-key

Manual Installation

For development or when Docker isn't available.

Step 1: Clone the Repository

git clone https://github.com/Real-PM/mail-rulez-public.git
cd mail-rulez-public

Step 2: Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate it
# On Linux/macOS:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Run the Application

python web/app.py

Screenshot: Manual installation terminal output

Initial Access

Once Mail-Rulez is running:

1. Open your web browser
2. Navigate to http://localhost:5001
3. You'll see the login screen

Screenshot: Initial login screen

Default Credentials

• Username: admin
• Password: changeme

⚠️ Important: Change the default password immediately after first login!

Verifying Installation

Health Check

# For Docker
docker exec mail-rulez curl -s localhost:5001/health

# For manual installation
curl -s localhost:5001/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.2"
}

Container Logs

# View recent logs
docker logs mail-rulez --tail 50

# Follow logs in real-time
docker logs -f mail-rulez

Next Steps

• First-Time Setup - Configure your admin account and system settings
• Account Configuration - Add your email accounts
• Quick Start Tutorial - Complete workflow guide

Troubleshooting Installation

Port Already in Use

If port 5001 is already in use:

# Use a different port
docker run -d \
  --name mail-rulez \
  -p 5002:5001 \
  -e PORT=5002 \
  ghcr.io/real-pm/mail-rulez:latest

Permission Errors

If you encounter permission errors with volumes:

# Create volumes with proper permissions
docker volume create mail_rulez_data
docker volume create mail_rulez_logs

# Then run with named volumes
docker run -d \
  --name mail-rulez \
  -p 5001:5001 \
  -v mail_rulez_data:/app/data \
  -v mail_rulez_logs:/app/logs \
  ghcr.io/real-pm/mail-rulez:latest

Can't Access Web Interface

1. Check container is running: docker ps
2. Check logs for errors: docker logs mail-rulez
3. Verify firewall allows port 5001
4. Try accessing via http://127.0.0.1:5001 instead of localhost

For more troubleshooting help, see our Troubleshooting Guide.