Quick Start¶

Get Smailander up and running in just 5 minutes! This guide will walk you through the fastest way to start monitoring email threats.

Prerequisites¶

Before you begin, make sure you have:

A domain name (e.g., yourdomain.com)
Access to DNS management
Basic familiarity with command line tools
A system running Linux, macOS, or Windows with WSL

No Domain Yet?

If you don't have a domain, you can use free subdomain services like Freenom or DuckDNS for testing.

Step 1: Clone and Install¶

Clone the Repository¶

git clone https://codeberg.org/smailander/smailander.git
cd smailander

Install Dependencies¶

On Linux/macOS:

# Install Python dependencies
pip install -r requirements.txt

On Windows (WSL):

pip install -r requirements.txt

Step 2: Configure Environment¶

Set Up Environment Variables¶

Create a .env file in the project root:

cp .env.example .env

Edit .env with your preferred values:

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

# Application
SECRET_KEY=your-super-secret-key-change-this
API_URL=https://api.smailander.com
FRONTEND_URL=https://smailander.com

# Security
ENCRYPTION_KEY=your-encryption-key-for-pii

Security Alert

Never commit .env files to version control. Use strong, unique secrets in production.

Initialize Database¶

# Run migrations
python scripts/migrate.py

# Seed initial data
python scripts/seed.py

Step 3: Start the Services¶

Start All Services¶

# Using Docker (recommended)
docker-compose up -d

# Or start services individually
python -m smailander.api &
python -m smailander.worker &
python -m smailander.dashboard &

Verify Installation¶

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

# Expected response:
# {"status":"healthy","database":"connected"}

Step 4: Create Your First Honeypot¶

Open your browser and navigate to http://localhost:3000
Click "Sign Up" and enter your email
Check your email for a magic link
Click the link to log in

Configure Your Domain¶

Navigate to Settings → Domains
Click Add Domain
Enter your domain (e.g., yourdomain.com)
Smailander will generate DNS records for you to configure

Create a Honeypot Email Address¶

Via Dashboard:

Navigate to Honeypots → Create New
Enter:
Local part: test-monitor
Domain: yourdomain.com
Purpose: Select "Monitoring"
Description: "Testing honeypot for initial setup"
Click Create Honeypot

Via API:

curl -X POST http://localhost:8000/api/v1/email-addresses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "test-monitor",
    "domain": "yourdomain.com",
    "purpose": "monitoring",
    "description": "Testing honeypot for initial setup"
  }'

DNS Configuration

After creating your first honeypot, Smailander will provide the DNS records you need to add to your domain. Once configured, Smailander handles all email processing internally.

Step 5: Test Your Setup¶

Send a Test Email¶

Send an email to your new honeypot address:

# Using mail command
echo "Test email" | mail -s "Test Subject" test-monitor@yourdomain.com

# Or using sendmail
echo "Test email body" | sendmail test-monitor@yourdomain.com

Check the Dashboard¶

Navigate to Dashboard
You should see:
Total Emails: 1
Threats Detected: 0 (this is a benign test email)
Recent Emails: Your test email should appear

Configure Webhook (Optional)¶

Create a webhook endpoint to receive real-time notifications:

curl -X POST http://localhost:8000/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-webhook-endpoint.com/emails",
    "events": ["email.received", "threat.detected"],
    "secret": "your-webhook-secret"
  }'

Step 6: Deploy to Production (Optional)¶

For production deployment, we recommend:

Using Docker¶

# Build production image
docker build -t smailander:latest .

# Run with environment file
docker run -d \
  --name smailander \
  --env-file .env \
  -p 8000:8000 \
  -p 3000:3000 \
  smailander:latest

Using Cloud Platforms¶

Vercel (Frontend):

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

Railway (Backend):

# Install Railway CLI
npm install -g @railway/cli

# Deploy
railway login
railway init
railway up

Common Quick Start Issues¶

Database Connection Failed¶

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Start if not running
sudo systemctl start postgresql

Port Already in Use¶

# Find process using port 8000
lsof -i :8000

# Kill the process
kill -9 <PID>

DNS Not Propagating¶

# Check DNS propagation
dig test-monitor.yourdomain.com MX

# Use online tools like https://dnschecker.org

What's Next?¶

Congratulations! You've set up Smailander and created your first honeypot. Here's what you can do next:

Learn More¶

Core Concepts - Understand how honeypots work
Dashboard Guide - Master the dashboard
API Documentation - Integrate with your systems

Advanced Setup¶

Installation - Detailed installation options
Integrations - Connect with other tools
Security - Hardening your deployment

Explore Features¶

Honeypots - Create and manage honeypots
Threat Detection - Understand threat analysis
Analytics - Build threat intelligence

Need Help?¶

Check our Troubleshooting guide
Visit our FAQ for common questions
Contact us for support

Ready to dive deeper? Check out the Core Concepts or explore the User Guide.