ECTLogger - Quick Start Guide

🚀 Get Started in 5 Minutes

System Requirements

⚠️ Servers with <2GB RAM will struggle to run ECTLogger reliably. See PRODUCTION-DEPLOYMENT.md for low-memory workarounds.

⚡ Speedrun Install (Recommended for Fresh Systems)

One command to download, then run the installer:

curl -fsSL https://raw.githubusercontent.com/bradbrownjr/ectlogger/main/bootstrap.sh | bash

This downloads the installer and shows you the command to run it. Just copy and run the command shown - the interactive installer will:

• Install Git, Python 3, Node.js 22 LTS, and build tools
• Clone the ECTLogger repository to ~/ectlogger
• Set up the Python virtual environment and install dependencies
• Walk you through email configuration (for magic link authentication)
• Optionally set up ECTLogger as a system service

Works on Debian, Ubuntu, Fedora, RHEL, Rocky, and macOS.

After it completes, just run ./start.sh to launch!

📋 Manual Installation

If you prefer to install manually or the speedrun doesn’t work for your system:

Prerequisites

• Python 3.9+ installed
• Node.js 18+ installed
• Email account for sending notifications (Gmail recommended)

Step 1: Download & Setup

Linux/macOS

# Clone the repository
git clone https://github.com/bradbrownjr/ectlogger.git
cd ectlogger

# Make scripts executable
chmod +x *.sh

# Run the installation script
./install.sh

Windows (PowerShell)

# Clone the repository
git clone https://github.com/bradbrownjr/ectlogger.git
cd ectlogger

# Run the startup script (it will install everything automatically)
.\start.ps1

The scripts will:

• Create Python virtual environment
• Install all backend dependencies
• Install all frontend dependencies
• Optionally set up systemd service (run on boot)
• Optionally set up Fail2Ban (block brute-force attacks)
• Optionally set up Caddy reverse proxy (automatic SSL)

Step 2: Configure Email

Before first use, configure email settings using the interactive wizard:

Linux/macOS

./configure.sh

Windows (PowerShell)

.\configure.ps1

The configuration wizard will:

• Generate a secure secret key
• Configure your email (SMTP) settings
• Set frontend and backend URLs
• Auto-detect Caddy/Nginx and configure frontend serving appropriately
• For production setups with HTTPS, automatically set SKIP_VITE=true so Caddy/Nginx serves the frontend

Or manually:

1. Copy .env.example to backend/.env
2. Edit backend/.env and set your email credentials

For Gmail:

• Go to Google Account Settings
• Security → 2-Step Verification → App passwords
• Generate an app password and use it in SMTP_PASSWORD

Step 3: Access the Application

Open your browser to:

• Application: http://localhost:3000
• API Documentation: http://localhost:8000/docs

Step 4: First Login

1. Enter your email address
2. Click “Send Magic Link”
3. Check your email
4. Click the link to sign in
5. You’re in! 🎉

Start the Application

Linux/macOS

./start.sh

Windows (PowerShell)

.\start.ps1

Manual Start (Alternative)

If you prefer to start servers manually:

Linux/macOS Backend

cd backend
source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Windows Backend

cd backend
.\venv\Scripts\Activate.ps1
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend (all platforms)

cd frontend
npm run dev

Common Issues

Port Already in Use

• Close other applications using ports 8000 or 3000
• Or modify ports in the configuration

Email Not Sending

• Verify SMTP credentials in .env
• For Gmail, use an App Password (not your regular password)
• Check that 2-Step Verification is enabled for Gmail

Dependencies Installation Failed

• Ensure Python and Node.js are in your PATH
• Try running installation manually:

  cd backend
  pip install -r requirements.txt
  cd ..\frontend
  npm install
  

⚠️ First Login - Administrator Setup

Important: The first user to sign in is automatically granted Administrator privileges. Before making your server publicly accessible, you should:

1. Complete first-time setup and configure email
2. Access the application and sign in with your email
3. Verify you have admin access (you’ll see the Admin panel in the navigation)
4. Only then expose the server to the network/internet

This ensures the server owner becomes the administrator before anyone else can access the system.

What’s Next?

See the full documentation:

• Self-Hosting Guide - Overview and requirements
• Manual Installation - Step-by-step manual installation
• Production Deployment - Deploy with SSL/HTTPS
• Development Guide - Development guide and project structure
• README - Feature overview

Getting Help

• Check the API documentation at http://localhost:8000/docs
• Review the documentation files for detailed configuration
• Open an issue on GitHub