Self-Hosting ECTLogger

ECTLogger is available as a hosted service at app.ectlogger.us, but you can also run your own instance on your own server.

Why Self-Host?

You might want to self-host ECTLogger if you:

• Need to operate in an air-gapped or offline environment
• Want full control over your data and infrastructure
• Have specific security or compliance requirements
• Want to customize the application for your organization
• Are running training exercises or testing scenarios

System Requirements

Hardware

⚠️ Servers with <2GB RAM will struggle during frontend builds. See Production Deployment for workarounds.

Software

Browser Support

Modern browsers: Chrome, Firefox, Safari, Edge (latest versions)

Technology Stack

• Frontend: React with TypeScript and Material-UI (MUI)
• Backend: Python FastAPI with async/await support
• Database: SQLAlchemy ORM (SQLite, PostgreSQL, MySQL)
• Authentication: OAuth2 + Magic Link email authentication
• Real-Time: WebSockets for live updates
• Email: SMTP with HTML templates

Installation Options

Quick Start (Recommended)

The fastest way to get ECTLogger running:

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

This single command:

• Installs all prerequisites (Git, Python, Node.js)
• Clones the repository
• Runs the interactive installer

See Quick Start Guide for detailed instructions.

Manual Installation

For environments where the automated installer isn’t suitable:

See Manual Installation Guide for step-by-step instructions.

Production Deployment

For internet-facing deployments with SSL/HTTPS:

See Production Deployment Guide for:

• Caddy or Nginx reverse proxy setup
• Automatic SSL certificates
• systemd service configuration
• Fail2Ban integration
• Security hardening

Configuration

Required Configuration

At minimum, you need to configure email for magic link authentication:

# backend/.env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=your-email@gmail.com
SMTP_FROM_NAME=ECTLogger

Use ./configure.sh (Linux/macOS) or .\configure.ps1 (Windows) for interactive configuration.

Optional Configuration

Running ECTLogger

Development Mode

# Linux/macOS
./start.sh

# Windows
.\start.ps1

Access at: http://localhost:3000

Production Mode

With systemd service installed:

sudo systemctl start ectlogger
sudo systemctl enable ectlogger  # Start on boot

Access via your configured domain with HTTPS.

Migration Between Environments

Use the migration scripts to move between development and production:

# Linux/macOS - Switch to production domain
./migrate.sh --host ect.example.com

# Windows - Switch to LAN IP
.\migrate.ps1 -LanIP 192.168.1.100

See Production Deployment for complete migration instructions.

Updating

Pull the latest changes and restart:

cd ~/ectlogger
git pull
./install.sh  # Reinstall dependencies if needed
sudo systemctl restart ectlogger

Backup & Recovery

Database Backup

SQLite (default):

cp backend/ectlogger.db backup/ectlogger-$(date +%Y%m%d).db

PostgreSQL:

pg_dump ectlogger > backup/ectlogger-$(date +%Y%m%d).sql

Configuration Backup

cp backend/.env backup/
cp frontend/.env backup/

Troubleshooting

Common Issues

Getting Help

• Check the API documentation when running
• Review logs: journalctl -u ectlogger -f (systemd)
• Open an issue on GitHub

Next Steps

• Quick Start — Get running in 5 minutes
• Production Deployment — Deploy with SSL
• Security — Security best practices
• Development Guide — Contribute to ECTLogger