OpenEFA Installer
Requirements & Design Decisions

1. Target Environment

Q: What Linux distribution(s) should the installation script support?

Rationale:

• Predictable environment for testing and support
• Most common deployment platform
• Reduces maintenance burden for initial release
• Can expand to other distros in future versions

2. Installation Scope

Q: Should the installer handle the complete email server stack, or assume some components are already configured?

Components Installed:

• Postfix (MTA)
• MariaDB/MySQL (database)
• Redis (queue)
• Python environment with dependencies
• OpenSpacy modules (tiered selection)
• Web interface (SpacyWeb)
• API services (3 ports: 5001, 5002, 5003)
• Systemd services

Tiered Module Selection

1. Tier 1 - Core: Required for basic email flow
2. Tier 2 - Additional: Standard security (user chooses)
3. Tier 3 - Advanced: Optional/resource-intensive (can be added later via secondary script)

Rationale: Allows users to get email flowing immediately with Tiers 1+2, then optionally add advanced features.

3. OpenSpacy Module Categories

Q: Which security modules belong in each tier?

Tier 1 - Core Modules (Required for basic email flow)

• Authentication (SPF/DKIM/DMARC)
• Email blocking (sender/domain/country rules)
• Basic spam scoring
• RBL checker (moved from Tier 2 - fundamental anti-spam measure)

Tier 2 - Additional Modules (Standard security)

• BEC detector + Typosquatting
• DNS reputation
• Obfuscation detector
• Marketing filter
• Funding spam detector

Tier 3 - Advanced Modules (Optional, resource-intensive)

• NER (Named Entity Recognition - SpaCy NLP models ~500MB)
• Thread awareness enhanced
• Conversation learning system
• Behavioral baseline
• PDF analyzer
• URL reputation
• Compliance module

Rationale:

• Tier 1 is lightweight and essential
• Tier 2 provides robust protection without heavy resources
• Tier 3 can be deferred to reduce install time and disk space

4. Initial Configuration Method

Q: How should the installer gather initial configuration details?

Prompts Required:

1. Initial domain to protect (e.g., example.com)
2. Database password (uses default db name: spacy_email_db, user: spacy_user)
3. Admin email and username for SpacyWeb
4. Admin password for SpacyWeb (with confirmation)
5. EFA/destination server IP (relay host, e.g., 192.168.1.100)
6. Internal DNS resolver IP (e.g., 192.168.1.10)

Rationale:

• More secure than default credentials
• Smart defaults reduce complexity
• All essential info gathered upfront
• No pre-configuration file to edit

5. Postfix Integration Strategy

Q: How should the installer configure Postfix to integrate with SpaCy?

Configuration Includes:

• main.cf - relay host, virtual domains, content filter
• master.cf - email_filter.py integration with 90s timeout
• DNS resolver settings
• Virtual domains for initial domain

Rationale:

• Clean Ubuntu install assumption makes configuration predictable
• Eliminates risk of breaking existing mail flow
• Users deploy OpenEFA on dedicated server/VM
• Full control over Postfix settings

6. Network Architecture & Deployment Model

Q: How should the installer help users understand/configure the network flow?

Network Flow:

Internet → OpenEFA/SpaCy → Existing EFA/MailGuard → Mail Server

Configuration:

• Single relay host (user specifies IP/hostname)
• Designed for placement in front of existing EFA appliance
• Advanced scenarios documented separately

Rationale:

• Most users will add SpaCy in front of existing EFA
• Simple, predictable configuration
• Serves 90% of use cases
• Multi-relay scenarios can be added post-install

7. Service Management & Startup

Q: What services need to be created and how should they start?

Services Installed & Enabled:

• spacy-db-processor.service - Database queue processor
• spacyweb.service - Web interface (port 5500)
• spacy-release-api.service - Release tracking (port 5001)
• spacy-whitelist-api.service - Whitelist API (port 5002)
• spacy-block-api.service - Block sender API (port 5003)
• Plus: postfix, mariadb, redis

Secondary Script Available:

• EFA integration script (optional, runs on existing EFA to configure API endpoints)
• Enables "Always Allow" and "Always Block" buttons in EFA interface

8. Web Interface Security & Access

Q: How should the installer handle SpacyWeb security setup?

Security Setup:

• Generate self-signed SSL certificate during install
• Prompt for admin username
• Prompt for admin email
• Prompt for admin password (with confirmation)
• Create first admin account in database immediately

Post-Install Upgrade Path:

• Users can add Let's Encrypt certificate later
• Documentation provided for SSL upgrade

9. File Ownership & Permissions

Q: What user/group should own the SpaCy installation?

Permissions:

• User/Group: spacy-filter
• Directories: 750 (rwxr-x---)
• Config files: 640 (rw-r-----)
• Installation directory: /opt/spacyserver
• Database user: spacy_user

Rationale:

• Matches current production setup
• Security best practices (least privilege)
• Unprivileged user reduces attack surface
• Strict permissions protect sensitive configs

10. Logging & Monitoring Setup

Q: How should the installer configure logging?

Logging Configuration:

• Default level: DEBUG/verbose (helps initial troubleshooting)
• Log rotation: Automatic via logrotate
• Log retention: Configurable (default 30 days)
• Log location: /opt/spacyserver/logs/
• Management tools: Full OpenSpacyMenu suite (23+ options)

Included Logs:

• Application logs (email_filter_error.log, db_processor.log, etc.)
• Postfix logs (via /var/log/mail.log)
• Systemd journal logs
• Installation log (install.log)

11. Database & Queue Configuration

Q: Should the installer create default database schema and initial data?

Database Setup:

• Create database: spacy_email_db
• Create user: spacy_user with prompted password
• Create all tables, indexes, constraints
• Add initial domain to client_domains table (active by default)
• Configure Postfix to accept mail for that domain
• Add domain to admin's authorized_domains in SpacyWeb
• Set up Redis queues

12. Dependencies & Package Management

Q: How should the installer handle Python dependencies and SpaCy NLP models?

Dependency Strategy:

• System packages: Via apt (postfix, mariadb-server, redis-server, python3-venv, etc.)
• Python packages: In virtual environment at /opt/spacyserver/venv
• Tier 1/2: No NLP models (fast install, ~50MB total)
• Tier 3: Download en_core_web_sm if user selects advanced modules (~15MB)

13. Post-Installation Testing & Validation

Q: Should the installer include automated testing to verify the installation?

Validation Tests (if user agrees):

• Check all services running (systemctl status)
• Verify database connectivity
• Test Redis queue
• Send test email through SpaCy → EFA server (validates full relay chain)
• Display SpacyWeb URL and login credentials
• Show "Next Steps" checklist

14. Error Handling & Rollback

Q: What should happen if the installation fails partway through?

Error Handling:

• Detect failures at each stage
• Automatic rollback to pre-install state
• Log all actions to /opt/spacyserver/logs/install.log
• Provide uninstall_spacy.sh script for complete removal

Rollback Capability:

• Remove installed packages
• Delete created users/groups
• Drop database and user
• Remove installation directory
• Restore original configs (if any modified)
• Display clear error message with log location

15. Update & Upgrade Path

Q: How should users update SpaCy after initial installation?

Update Strategy:

• Installer detects existing installation → offers upgrade mode
• Automatic backup of configs and database before upgrade
• Preserve user configurations (merge new defaults with existing)
• Run database migrations automatically (versioned schema updates)
• Auto-restart services after successful upgrade

Future Package Manager:

• Structure prepared for apt repository packaging
• Version tracking built into database schema
• Clean upgrade path from script to package manager

16. Distribution & Licensing

Q: How will users obtain and run the installer?

Distribution Method:

curl -sSL https://install.openefa.com/install.sh | sudo bash

Alternative Methods:

• Git clone from repository
• Download release tarball from GitHub

Licensing:

• License: GPL (GNU General Public License)
• Copyright: Include LICENSE file with attribution
• Headers: License headers in all scripts

Branding:

• Project Name: OpenEFA (successor to EFA project)
• Technology: OpenSpacy modules (AI engine)
• Website: https://openefa.com
• Community Forum: https://forum.openefa.com
• Installation Banner: Display OpenEFA logo/name during install

Installation Flow Summary

1. Pre-flight checks (OS version, root privileges, internet connectivity)
2. Display welcome banner (OpenEFA branding)
3. Interactive prompts (domain, passwords, IPs)
4. Package installation (system packages via apt)
5. User/group creation (spacy-filter)
6. Python virtual environment setup
7. Database installation and schema creation
8. Redis queue configuration
9. Postfix configuration (relay to EFA)
10. OpenSpacy module tier selection
11. SpacyWeb installation and SSL certificate generation
12. API services installation (3 services)
13. Systemd service creation and enablement
14. Log rotation configuration
15. OpenSpacyMenu tools installation
16. Post-install validation (optional test email)
17. Display completion message with URLs and credentials
18. Offer EFA integration script

Deliverables

1. install.sh - Main installation script
2. uninstall.sh - Complete removal script
3. efa_integration.sh - EFA API configuration (optional)
4. README.md - Installation documentation
5. LICENSE - GPL license file
6. INSTALLER_DESIGN.md - Technical design document

Development & Testing Plan

Testing Environment:

• Fresh Ubuntu 24.04 server (separate from production 192.168.50.89)
• SSH access for remote development
• Spare domain for real-world email testing
• Snapshot capability for restore/retry cycles

Methodology:

1. Design scripts on production server (documentation only)
2. Switch to test server for execution
3. Snapshot clean state
4. Run installer
5. Test functionality
6. Restore snapshot
7. Refine and repeat

Next Steps

• ✅ Requirements gathering complete
• ☐ Design installer architecture
• ☐ Write installation script
• ☐ Write uninstall script
• ☐ Create EFA integration script
• ☐ Write documentation
• ☐ Test on fresh Ubuntu 24.04
• ☐ Release to open source community