Installation¶

This guide covers detailed installation options for Smailander across different environments and deployment scenarios.

System Requirements¶

Minimum Requirements¶

Component	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Storage	20 GB	50+ GB SSD
Python	3.10+	3.11+
PostgreSQL	14+	15+

Supported Operating Systems¶

Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+, RHEL 9+
macOS: Monterey 12+, Ventura 13+, Sonoma 14+
Windows: Windows 10/11 with WSL2

Installation Methods¶

Method 1: Docker (Recommended)¶

Docker provides the easiest and most reproducible installation method.

Prerequisites¶

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Quick Install¶

# Clone repository
git clone https://codeberg.org/smailander/smailander.git
cd smailander

# Build and start services
docker-compose up -d

# Check status
docker-compose ps

Docker Compose Configuration¶

The docker-compose.yml includes:

PostgreSQL: Database for email storage
API Server: REST API backend
Worker: Background job processing
Dashboard: Web interface
Core Services: Built-in malware scanning, spam detection, and threat analysis

Method 2: Manual Installation¶

For maximum control, install each component manually.

Step 1: Install System Dependencies¶

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y \
    python3 python3-pip python3-venv \
    postgresql postgresql-contrib \
    nginx \
    certbot

CentOS/RHEL:

sudo yum update
sudo yum install -y \
    python3 python3-pip \
    postgresql-server postgresql-contrib \
    nginx \
    certbot

macOS (with Homebrew):

brew install python postgresql nginx certbot

Step 2: Create Python Virtual Environment¶

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

# Install Python dependencies
pip install --upgrade pip
pip install -r requirements.txt

Step 3: Configure PostgreSQL¶

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql

-- In PostgreSQL prompt
CREATE DATABASE smailander;
CREATE USER smailander WITH PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE smailander TO smailander;
\q

Step 4: Initialize Application¶

# Set up environment
cp .env.example .env
nano .env  # Edit with your configuration

# Run database migrations
python scripts/migrate.py

# Seed initial data
python scripts/seed.py

Method 3: Cloud Installation¶

AWS (Amazon Web Services)¶

# Install AWS CLI
pip install awscli

# Configure AWS credentials
aws configure

# Deploy using Terraform
cd terraform/aws
terraform init
terraform apply

Google Cloud Platform¶

# Install gcloud CLI
curl https://sdk.cloud.google.com | bash

# Authenticate
gcloud auth login

# Deploy
cd terraform/gcp
terraform init
terraform apply

Azure¶

# Install Azure CLI
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Login
az login

# Deploy
cd terraform/azure
terraform init
terraform apply

Configuration¶

Environment Variables¶

Create .env file with following variables:

# Database
DATABASE_URL=postgresql://smailander:password@localhost:5432/smailander

# Application
SECRET_KEY=your-super-secret-key-min-32-chars
API_URL=https://api.smailander.com
FRONTEND_URL=https://smailander.com

# Security
ENCRYPTION_KEY=your-32-character-encryption-key

# Monitoring
SENTRY_DSN=your-sentry-dsn
LOG_LEVEL=INFO

Production Configuration¶

For production, additional security measures:

# Enable HTTPS
FORCE_HTTPS=true
SSL_CERT_PATH=/etc/letsencrypt/live/smailander.com/fullchain.pem
SSL_KEY_PATH=/etc/letsencrypt/live/smailander.com/privkey.pem

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=100

# Session Security
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_HTTPONLY=true
SESSION_COOKIE_SAMESITE=strict

# CORS
CORS_ORIGINS=https://smailander.com,https://api.smailander.com

SSL/TLS Configuration¶

Using Let's Encrypt¶

# Install Certbot
sudo apt-get install certbot

# Generate certificate
sudo certbot certonly --standalone -d smailander.com -d api.smailander.com

# Configure auto-renewal
sudo certbot renew --dry-run

Using Nginx¶

Create /etc/nginx/sites-available/smailander:

server {
    listen 80;
    server_name smailander.com www.smailander.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name smailander.com www.smailander.com;

    ssl_certificate /etc/letsencrypt/live/smailander.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/smailander.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location /api {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Enable site:

sudo ln -s /etc/nginx/sites-available/smailander /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Verification¶

Check All Services¶

# Check API health
curl http://localhost:8000/health

# Check dashboard
curl http://localhost:3000

# Check database
python -c "import psycopg2; print('Database OK')"

Run Diagnostics¶

# Run diagnostic script
python scripts/diagnose.py

# Expected output:
# ✓ Database connection: OK
# ✓ Core services: OK
# ✓ All systems operational

Troubleshooting¶

Port Conflicts¶

# Check which ports are in use
lsof -i :3000 -i :8000 -i :5432

# Kill process using specific port
kill -9 <PID>

Database Connection Issues¶

# Check PostgreSQL status
sudo systemctl status postgresql

# Check connection string
psql postgresql://smailander:password@localhost:5432/smailander

# View PostgreSQL logs
sudo tail -f /var/log/postgresql/postgresql-*.log

Permission Issues¶

# Fix file permissions
sudo chown -R $USER:$USER /var/log/smailander
sudo chmod -R 755 /var/log/smailander

Updates and Maintenance¶

Update Smailander¶

# Pull latest changes
git pull origin main

# Update dependencies
pip install -r requirements.txt --upgrade

# Run migrations
python scripts/migrate.py

# Restart services
sudo systemctl restart smailander-api
sudo systemctl restart smailander-worker

Backup Database¶

# Automated backup script
#!/bin/bash
BACKUP_DIR="/backups"
DATE=$(date +%Y%m%d_%H%M%S)
pg_dump -U smailander smailander > "$BACKUP_DIR/smailander_$DATE.sql"

# Keep last 7 days
find $BACKUP_DIR -name "smailander_*.sql" -mtime +7 -delete

Next Steps¶

After installation:

Quick Start - Create your first honeypot
Core Concepts - Understand the system
User Guide - Learn to use the platform
Security - Harden your deployment

Need Help?¶

Troubleshooting - Common issues and solutions
FAQ - Frequently asked questions
Contact - Get support