EmailArchiveOS

A self-hosted email archiving service with React frontend and Node.js backend, featuring full-text search, user authentication, and comprehensive email management capabilities.

🚀 Features

Core Functionality

• 📤 Manual Upload: Drag & Drop interface for .eml/.msg files
• 🔍 Full-Text Search: Powered by Elasticsearch with advanced query capabilities
• 📎 Attachment Extraction: Automatic storage and preview of email attachments
• 📊 Metadata Extraction: Date, sender, recipient, subject, and more
• 🔄 Deduplication: Based on Message-ID to prevent duplicate emails
• 🏷️ Categorization: Automatic tagging and label management
• 🧵 Thread View: Email conversation threading and display
• 📤 Export Functions: JSON export of search results
• 👥 User Authentication: Multi-user support with role-based access control
• 📈 Analytics Dashboard: Comprehensive statistics and insights

Technical Features

• 🐳 Docker Compose: Easy deployment solution
• ⚛️ React + Vite: Modern, fast frontend
• 📘 TypeScript: Type safety across the entire stack
• 🔍 Elasticsearch: High-performance full-text search
• 🐘 PostgreSQL: Reliable metadata storage
• 🔴 Redis: Caching and job queues
• 🔐 JWT Authentication: Secure user authentication
• 🛡️ Security: bcrypt password hashing, CORS protection, input validation

🏗️ Architecture

┌─ Frontend (React + Vite + TypeScript)
├─ Backend (Node.js + Express + TypeScript)
├─ Database (PostgreSQL)
├─ Search Engine (Elasticsearch)
├─ Cache/Queue (Redis)
└─ File Storage (Docker Volumes)

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 18+ (for local development)

Starting the Application

1. Clone the repository

git clone <repository-url>
cd EmailArchiveOS

2. Automatic startup (recommended)

./start.sh

The startup script automatically:

• ✅ Checks if Docker is installed (installs automatically if needed)
• ✅ Checks if Docker Compose v2 is available (installs automatically if needed)
• ✅ Starts Docker Desktop on macOS automatically
• ✅ Creates necessary directories
• ✅ Starts all services
• ✅ Waits for all services to be ready
• ✅ Performs health checks
• ✅ Shows final status overview

Supported operating systems:

• 🐧 Ubuntu/Debian (with apt)
• 🎩 CentOS/RHEL (with yum)
• 🏗️ Arch Linux (with pacman)
• 🍎 macOS (with Homebrew)

3. Manual startup (optional)

docker-compose up -d
# or with Docker Compose v2:
docker compose up -d

4. Stop services

./stop.sh

5. Access the application

• Frontend: http://localhost:3000
• Backend API: http://localhost:5000
• Backend Health Check: http://localhost:5000/health

First Steps

1. Prepare email files

   • Export emails as .eml files from your email client
   • Or use .msg files (Outlook format)

2. Login to the system

   • Default admin credentials:
     • Email: admin@emailarchive.local
     • Password: admin123
   • ⚠️ Important: Change the password after first login!

3. Upload emails

   • Navigate to http://localhost:3000/upload
   • Drag & Drop your email files
   • Wait for processing to complete

4. Search and browse emails

   • Use the search function at http://localhost:3000/search
   • Or browse the dashboard for an overview

👥 User Management

Roles

• Admin: Full system permissions, can create and manage users
• User: Can use all email archiving functions

Authentication Features

• Secure JWT-based authentication (24h token validity)
• Automatic token renewal during active usage
• bcrypt password hashing (12 rounds)
• Soft-delete for users (deactivation instead of deletion)

🛠️ Development

Local Development

1. Install dependencies

# Frontend
cd frontend
npm install

# Backend
cd ../backend
npm install

2. Start services (DB, Elasticsearch, Redis only)

docker-compose up -d postgres elasticsearch redis

3. Start frontend

cd frontend
npm run dev

4. Start backend

cd backend
npm run dev

Project Structure

EmailArchiveOS/
├── docker-compose.yml          # Service orchestration
├── start.sh                    # Intelligent startup script
├── stop.sh                     # Safe shutdown script
├── frontend/
│   ├── src/
│   │   ├── components/         # React components
│   │   ├── pages/             # Page components
│   │   │   ├── Dashboard.tsx  # Main dashboard
│   │   │   ├── Upload.tsx     # File upload interface
│   │   │   ├── Search.tsx     # Search functionality
│   │   │   ├── Archive.tsx    # Email archive view
│   │   │   ├── Labels.tsx     # Label management
│   │   │   ├── EmailView.tsx  # Individual email view
│   │   │   ├── Login.tsx      # Authentication
│   │   │   ├── UserManagement.tsx # Admin user management
│   │   │   └── Settings.tsx   # Application settings
│   │   ├── services/          # API services
│   │   ├── contexts/          # React contexts
│   │   └── types/             # TypeScript types
│   ├── package.json
│   └── Dockerfile
├── backend/
│   ├── src/
│   │   ├── routes/            # Express routes
│   │   │   ├── authRoutes.ts  # Authentication endpoints
│   │   │   ├── emailRoutes.ts # Email management
│   │   │   ├── labelsRoutes.ts # Label operations
│   │   │   ├── statsRoutes.ts # Analytics endpoints
│   │   │   └── databaseRoutes.ts # Database operations
│   │   ├── services/          # Business logic
│   │   │   ├── EmailService.ts # Email processing
│   │   │   ├── SearchService.ts # Search functionality
│   │   │   ├── UserService.ts # User management
│   │   │   ├── ElasticsearchService.ts # Search engine
│   │   │   └── DatabaseService.ts # Database operations
│   │   ├── middleware/        # Express middleware
│   │   │   └── auth.ts        # Authentication middleware
│   │   ├── database/          # DB schema & migrations
│   │   └── types/             # TypeScript types
│   ├── package.json
│   └── Dockerfile
└── README.md

📚 API Documentation

Authentication Endpoints

• POST /api/auth/login - User login
• GET /api/auth/profile - Current user profile
• POST /api/auth/change-password - Change password
• POST /api/auth/logout - Logout

Email Endpoints

• POST /api/emails/upload - Upload email file
• GET /api/emails/recent - Get recent emails
• POST /api/emails/search - Search emails
• GET /api/emails/:id - Get email details
• GET /api/emails/thread/:threadId - Get email thread
• PATCH /api/emails/:id/labels - Update email labels
• GET /api/emails/:id/attachments/:filename - Download attachment

Admin Endpoints

• POST /api/auth/users - Create new user
• GET /api/auth/users - List all users
• PATCH /api/auth/users/:id - Edit user
• DELETE /api/auth/users/:id - Delete user

Statistics & Labels

• GET /api/stats - Get system statistics
• GET /api/labels - Get all available labels

⚙️ Configuration

Environment Variables

Backend (.env)

PORT=5000
FRONTEND_URL=http://localhost:3000
DATABASE_URL=postgresql://emailarchive:password@localhost:5432/emailarchive
ELASTICSEARCH_URL=http://localhost:9200
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-very-secure-random-jwt-secret-key-here

Frontend (.env)

VITE_API_URL=http://localhost:5000/api

🚀 Deployment

Production Setup

1. Configure environment

cp .env.example .env
# Edit .env with production values

2. SSL/HTTPS configuration

# docker-compose.prod.yml
# Add reverse proxy (nginx) configuration

3. Backup strategy

# PostgreSQL backup
docker-compose exec postgres pg_dump -U emailarchive emailarchive > backup.sql

# Elasticsearch backup
# Configure Elasticsearch snapshots

📋 Script Management

Available Scripts

🚀 start.sh - Intelligent startup

./start.sh

• Automatic Docker/Docker Compose installation
• OS-specific installation procedures
• Health checks and status monitoring
• Automatic browser opening

🛑 stop.sh - Safe shutdown

./stop.sh

• Confirmation before stopping
• Option to delete data volumes
• Overview of all stopped services

📋 Useful Commands

# Check service status
docker compose ps
# or
docker-compose ps

# View logs
docker compose logs -f
docker compose logs backend
docker compose logs frontend

# Restart services
docker compose restart

# Restart single service
docker compose restart backend

# Cleanup (images, containers, etc.)
docker system prune -a

🔧 Troubleshooting

Common Issues

Docker Installation Errors

# Ensure curl is available
sudo apt-get update && sudo apt-get install -y curl

# For macOS: Install Homebrew if not available
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Elasticsearch Won't Start

# Increase vm.max_map_count
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# The startup script warns about this automatically

Upload Errors

• Check file size (Max 50MB)
• Ensure storage directory is writable
• Check backend logs: docker compose logs backend

Search Not Working

• Wait for Elasticsearch to fully start
• Check Elasticsearch status: curl http://localhost:9200/_health
• The startup script monitors this automatically

Docker Desktop on macOS

• The startup script starts Docker Desktop automatically
• If issues: Open Docker Desktop manually from Applications

Permission Errors

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Then log out and log back in

Authentication Issues

• Verify JWT_SECRET is set in backend .env
• Check user credentials and role assignments
• Review backend logs for detailed error messages

🗺️ Roadmap

Planned Features

• IMAP Sync Integration
• Automatic Email Classification (AI)
• Mobile App
• Advanced Analytics Dashboard
• Email Reply Integration
• Advanced Search Filters
• Bulk Operations
• Email Templates
• API Rate Limiting
• Multi-language Support

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Test thoroughly
5. Create a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

For issues and questions:

1. Check the troubleshooting section
2. Review the logs: docker compose logs
3. Create an issue on GitHub
4. Check the documentation in AUTHENTICATION_SETUP.md

---

EmailArchiveOS - Your self-hosted email archiving solution with powerful search, user management, and comprehensive email processing capabilities.