📌 New users: Start with Quick Start Guide for an easier automated setup!

This guide covers manual step-by-step installation for advanced users, developers, or deployment environments where the automated scripts aren't suitable.

ECTLogger is a modern web-based net logger for Emergency Communications Teams and SKYWARN spotter nets. It features real-time check-ins, multi-frequency support, and comprehensive net management.

• Backend: Python FastAPI with SQLAlchemy ORM
• Frontend: React with TypeScript and Material-UI (MUI)
• Database: SQLite (default), PostgreSQL or MySQL supported
• Authentication: OAuth2 (Google, Microsoft, GitHub) + Magic Link email authentication
• Real-time: WebSockets for live updates

• Python 3.9 or higher
• Node.js 18 or higher
• Git

git clone https://github.com/yourusername/ectlogger.git
cd ectlogger

Linux/macOS:

cd backend
python3 -m venv venv
source venv/bin/activate

Windows:

cd backend
python -m venv venv
.\venv\Scripts\Activate.ps1

pip install -r requirements.txt

Copy the example environment file:

Linux/macOS:

cp .env.example backend/.env

Windows:

Copy-Item .env.example backend\.env

Edit backend/.env file with your settings:

# Database (SQLite by default)
DATABASE_URL=sqlite:///./ectlogger.db

# Security - GENERATE A STRONG SECRET KEY!
SECRET_KEY=your-very-secure-secret-key-change-this-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440  # 24 hours

# Frontend URL
FRONTEND_URL=http://localhost:3000

# Email Configuration (Required for authentication)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=[email protected]
SMTP_FROM_NAME=ECTLogger

# OAuth Providers (Optional - configure as needed)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Frontend Serving (Production only)
# Set to true when using Caddy/Nginx to serve static files from frontend/dist/
# SKIP_VITE=true

Important Notes:

• Generate a secure SECRET_KEY using: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
• For Gmail SMTP, you need to create an "App Password" in your Google Account settings
• OAuth providers are optional and can be added later

The database will be automatically created on first run. No manual initialization needed.

Open a new terminal window:

cd frontend

npm install

Create .env.local file if you need to customize the API URL:

VITE_API_URL=http://localhost:8000/api

Note: The /api suffix is required. All backend routes are prefixed with /api for reverse proxy compatibility.

Linux/macOS:

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

Windows:

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

The API will be available at: http://localhost:8000 API documentation: http://localhost:8000/docs

In a separate terminal:

cd frontend
npm run dev

The application will be available at: http://localhost:3000

Linux/macOS:

chmod +x *.sh
./install.sh    # One-time setup
./configure.sh  # Configure email and database
./start.sh      # Start both servers

Windows:

.\start.ps1     # Install and start

1. Open your browser to http://localhost:3000
2. Click "Send Magic Link"
3. Enter your email address
4. Check your email for the magic link
5. Click the link to sign in
6. Your account will be created automatically

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URI: http://localhost:8000/auth/oauth/google/callback
6. Copy Client ID and Secret to .env file

1. Go to Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Register new application
4. Add redirect URI: http://localhost:8000/auth/oauth/microsoft/callback
5. Create client secret
6. Copy Application (client) ID and secret to .env file

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create new OAuth App
3. Set callback URL: http://localhost:8000/auth/oauth/github/callback
4. Copy Client ID and generate Client Secret
5. Add to .env file

1. Install PostgreSQL

   # Ubuntu/Debian
   sudo apt install postgresql postgresql-contrib
   
   # macOS
   brew install postgresql

2. Create database:

   sudo -u postgres createdb ectlogger
   sudo -u postgres createuser your_username

3. Update backend/.env:

   DATABASE_URL=postgresql+asyncpg://username:password@localhost/ectlogger

1. Install MySQL

   # Ubuntu/Debian
   sudo apt install mysql-server
   
   # macOS
   brew install mysql

2. Create database:

   CREATE DATABASE ectlogger;
   CREATE USER 'your_user'@'localhost' IDENTIFIED BY 'password';
   GRANT ALL PRIVILEGES ON ectlogger.* TO 'your_user'@'localhost';

3. Update backend/.env:

   DATABASE_URL=mysql+aiomysql://username:password@localhost/ectlogger

1. Set APP_ENV=production in backend/.env

2. Use a production WSGI server:

   pip install gunicorn
   gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

3. Set up reverse proxy (nginx or Apache)

4. Enable HTTPS with SSL certificates (Let's Encrypt)

5. Configure firewall rules

cd frontend
npm run build

The dist folder contains production-ready static files.

Important: If using a reverse proxy (Caddy, nginx) to serve the frontend, ensure the web server user can read the files. Home directories are typically mode 700, which prevents access:

# Make directories traversable for the web server
chmod 755 /home/your-user
chmod 755 /path/to/ectlogger
chmod 755 /path/to/ectlogger/frontend
chmod -R a+rX /path/to/ectlogger/frontend/dist

Create /etc/systemd/system/ectlogger-backend.service:

[Unit]
Description=ECTLogger Backend
After=network.target

[Service]
Type=notify
User=your-user
WorkingDirectory=/path/to/ectlogger/backend
Environment="PATH=/path/to/ectlogger/backend/venv/bin"
ExecStart=/path/to/ectlogger/backend/venv/bin/gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable ectlogger-backend
sudo systemctl start ectlogger-backend

Serve with:

• Nginx
• Apache
• Caddy
• Any static file hosting service

Update these settings:

• Set strong SECRET_KEY
• Use production database (PostgreSQL recommended)
• Configure production SMTP server
• Set FRONTEND_URL to your domain
• Enable HTTPS
• Configure OAuth redirect URIs for your domain

• Verify SMTP credentials
• For Gmail, ensure "Less secure app access" is enabled or use App Password
• Check firewall settings for SMTP port

• Ensure database server is running
• Verify connection string in DATABASE_URL
• Check database user permissions

• Ensure both frontend and backend are running
• Check CORS settings in backend/app/main.py
• Verify WebSocket URL in frontend

The lint errors you're seeing are expected before dependencies are installed. They will resolve after running:

• Backend: pip install -r requirements.txt
• Frontend: npm install

• Guest: View-only access to active nets
• User: Can check in to nets, participate in chat
• NCS: Can create and manage nets, designate loggers
• Admin: Full system access, user management

💡 Note: The first user to sign in is automatically granted Administrator privileges. Make sure to sign in before making the server publicly accessible.

• API Documentation: http://localhost:8000/docs (when backend is running)
• GitHub Issues: Report bugs and feature requests
• README.md: Feature overview and requirements

MIT License - See LICENSE file for details