Skip to content

INSTALLATION.md

Latest commit

 

History

History
421 lines (333 loc) · 11 KB

INSTALLATION.md

File metadata and controls

421 lines (333 loc) · 11 KB
Raw

MailGrid Installation Guide

Multiple installation methods available for all major platforms with optimized binaries.

Quick Installation

Linux & macOS (One-liner)

curl -sSL https://raw.githubusercontent.com/bravo1goingdark/mailgrid/main/install.sh | bash

Windows (PowerShell)

Quick Install (Recommended)

# Basic installation
iwr -useb https://raw.githubusercontent.com/bravo1goingdark/mailgrid/main/install.ps1 | iex
 
# Enhanced installation with shortcuts and Windows Terminal integration
iwr -useb https://raw.githubusercontent.com/bravo1goingdark/mailgrid/main/install-enhanced.ps1 | iex

Advanced Installation Options

# Install with PATH integration and shortcuts
.\install-enhanced.ps1 -AddToPath -CreateShortcuts
 
# Install specific version with Windows Terminal profile
.\install-enhanced.ps1 -Version v1.0.0 -WindowsTerminalProfile
 
# Check for updates
.\install-enhanced.ps1 -CheckUpdates

Direct Downloads

Windows

Architecture Download Size
x64 mailgrid-windows-amd64.exe.zip ~3.7 MB
ARM64 mailgrid-windows-arm64.exe.zip ~3.3 MB

macOS

Platform Download Size
Intel Macs mailgrid-macos-intel.tar.gz ~4.2 MB
Apple Silicon mailgrid-macos-apple-silicon.tar.gz ~4.0 MB

Linux

Architecture Download Size
x64 mailgrid-linux-amd64.tar.gz ~4.1 MB
ARM64 mailgrid-linux-arm64.tar.gz ~3.9 MB
386 mailgrid-linux-386.tar.gz ~3.8 MB

FreeBSD

Architecture Download Size
x64 mailgrid-freebsd-amd64.tar.gz ~4.1 MB

Verify Downloads

All releases include SHA256 checksums for verification:

# Download checksums
curl -sSL https://github.com/bravo1goingdark/mailgrid/releases/latest/download/checksums.txt
 
# Verify (Linux/macOS)
sha256sum -c checksums.txt
 
# Verify (Windows PowerShell)
Get-FileHash mailgrid-windows-amd64.exe -Algorithm SHA256

Package Managers

Go Install

go install github.com/bravo1goingdark/mailgrid/cmd/mailgrid@latest

Homebrew (macOS/Linux)

brew tap bravo1goingdark/tap
brew install mailgrid

Windows Package Managers

Winget (Windows Package Manager)

# Install MailGrid
winget install MailGrid.MailGrid
 
# Search for MailGrid
winget search mailgrid
 
# Upgrade MailGrid
winget upgrade MailGrid.MailGrid

Chocolatey

# Install MailGrid
choco install mailgrid
 
# Upgrade MailGrid
choco upgrade mailgrid
 
# Uninstall MailGrid
choco uninstall mailgrid

Scoop

# Add bucket (first time only)
scoop bucket add mailgrid https://github.com/bravo1goingdark/scoop-mailgrid
 
# Install MailGrid
scoop install mailgrid
 
# Update MailGrid
scoop update mailgrid

Configuration

MailGrid requires an SMTP configuration file to send emails. The config file path is specified using the --env flag.

Basic Configuration

Create a config.json file:

{
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "username": "your-email@gmail.com",
    "password": "your-app-password",
    "from": "your-email@gmail.com"
  },
  "rate_limit": 10,
  "timeout_ms": 5000
}

Configuration File Locations

Using example config:

# Copy example config (from project directory)
cp example/config.json ./my-config.json
 
# Edit with your SMTP details
nano my-config.json
 
# Use with mailgrid
mailgrid --env my-config.json --to test@example.com --subject "Test" --text "Hello!"

Common config file locations:

  • Windows: C:\Users\YourName\mailgrid-config.json
  • Linux/macOS: ~/.config/mailgrid/config.json or ~/mailgrid-config.json
  • Project directory: ./config.json

SMTP Provider Examples

Gmail (App Password required)

{
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "username": "your-email@gmail.com",
    "password": "your-16-char-app-password",
    "from": "your-email@gmail.com"
  },
  "rate_limit": 10,
  "timeout_ms": 5000
}

Outlook/Hotmail

{
  "smtp": {
    "host": "smtp-mail.outlook.com",
    "port": 587,
    "username": "your-email@outlook.com",
    "password": "your-password",
    "from": "your-email@outlook.com"
  },
  "rate_limit": 5,
  "timeout_ms": 10000
}

SendGrid

{
  "smtp": {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "username": "apikey",
    "password": "your-sendgrid-api-key",
    "from": "noreply@yourdomain.com"
  },
  "rate_limit": 100,
  "timeout_ms": 5000
}

Quick Test

After installation, test with:

mailgrid --to you@example.com \
          --subject "MailGrid Test" \
          --text "Hello from MailGrid v1.0.0!" \
          --env config.json

Build from Source

For advanced users or contributors:

# Clone repository
git clone https://github.com/bravo1goingdark/mailgrid.git
cd mailgrid
 
# Build current platform
make build
 
# Build all platforms
make release
 
# Run tests
make test

System Requirements

Minimum Requirements

  • OS: Windows 10+, Linux (any modern distro), macOS 10.15+, FreeBSD 12+
  • Memory: 50MB RAM (base usage)
  • Disk: 20MB for binary + database storage
  • Network: Internet access for SMTP connections

Recommended for Production

  • Memory: 200MB-1GB RAM (depending on volume)
  • CPU: 2+ cores for high-throughput scenarios
  • Disk: SSD recommended for database performance
  • Network: Stable connection to SMTP providers

Troubleshooting

Configuration Errors

"failed to load config: open config : no such file"

# Error means --env flag is missing or config file doesn't exist
# Solution 1: Use --env flag with config file path
mailgrid --env ./config.json --to test@example.com --subject "Test" --text "Hello"
 
# Solution 2: Copy example config if in project directory
cp example/config.json ./my-config.json
mailgrid --env ./my-config.json --to test@example.com --subject "Test" --text "Hello"
 
# Solution 3: Create config file from scratch
echo '{
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "username": "your-email@gmail.com",
    "password": "your-app-password",
    "from": "your-email@gmail.com"
  },
  "rate_limit": 10,
  "timeout_ms": 5000
}' > config.json

"decode config JSON" error

# JSON syntax error in config file
# Check for:
# - Missing commas
# - Extra commas
# - Unmatched quotes/braces
# - Invalid escape characters
 
# Validate JSON syntax online or with:
python -m json.tool config.json  # Python
jq . config.json               # jq tool

"connection refused" or SMTP errors

# Test with dry-run first
mailgrid --env config.json --to test@example.com --subject "Test" --text "Hello" --dry-run
 
# Check SMTP settings:
# - Correct host and port
# - Valid username/password
# - Enable "Less secure app access" for Gmail or use App Password
# - Check firewall/network restrictions

Permission Errors (Linux/macOS)

# Make binary executable
chmod +x mailgrid
 
# Install to system directory (requires sudo)
sudo cp mailgrid /usr/local/bin/

Windows Installation Issues

Execution Policy (PowerShell Script Blocked)

# Allow script execution
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
# Unblock downloaded file
Unblock-File mailgrid.exe

Manual Installation (if script fails)

# Create installation directory
$installDir = "$env:LOCALAPPDATA\mailgrid\bin"
New-Item -ItemType Directory -Force -Path $installDir
 
# Download and extract binary
$downloadUrl = "https://github.com/bravo1goingdark/mailgrid/releases/latest/download/mailgrid-windows-amd64.exe.zip"
Invoke-WebRequest -Uri $downloadUrl -OutFile "$env:TEMP\mailgrid.zip"
Expand-Archive -Path "$env:TEMP\mailgrid.zip" -DestinationPath $installDir -Force
 
# Add to PATH (current session)
$env:PATH += ";$installDir"
 
# Add to PATH (permanent - requires restart of terminal)
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($currentPath -notlike "*$installDir*") {
    [Environment]::SetEnvironmentVariable("PATH", "$currentPath;$installDir", "User")
    Write-Host "MailGrid added to PATH. Restart your terminal to use 'mailgrid' command."
}
 
# Test installation
mailgrid --help

PATH Configuration Issues

# Check if mailgrid is in PATH
Get-Command mailgrid -ErrorAction SilentlyContinue
 
# If not found, manually add to directory to PATH
$mailgridPath = "$env:LOCALAPPDATA\mailgrid\bin"
if (Test-Path $mailgridPath) {
    $env:PATH += ";$mailgridPath"
    Write-Host "Added $mailgridPath to current session PATH"
}
 
# Verify installation
mailgrid --version

"mailgrid not recognized as command" Error

# Option 1: Use full path temporarily
& "$env:LOCALAPPDATA\mailgrid\bin\mailgrid.exe" --help
 
# Option 2: Refresh PATH in current session
$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH","User")
 
# Option 3: Restart PowerShell/Command Prompt
# Close and reopen your terminal

Performance Tips

High-Volume Sending

# Increase concurrency and batch size
mailgrid --csv large-list.csv \
          --concurrency 10 \
          --batch-size 100 \
          --template newsletter.html

Memory Optimization

# Limit connection pool for low-memory systems
export MAILGRID_MAX_CONNECTIONS=5

Monitoring

# Check metrics endpoint
curl http://localhost:8090/metrics
 
# Monitor health
curl http://localhost:8090/health

Next Steps

After installation:

  1. Read CLI Reference
  2. Check Usage Examples
  3. Review Performance Guide
  4. Report issues on GitHub

Need Help?