Menu ▾ ▴

GETTING_STARTED

Robert Trenaman

Getting Started Guide

Welcome to the Open Source Site Tracking getting started guide. This document will help you set up and start using the platform quickly.

Prerequisites

Before you begin, ensure you have the following installed:

  • Python 3.8+ - Backend development environment
  • Node.js 16+ - Frontend development environment
  • Git - Version control system
  • Docker (optional) - Containerized deployment
  • PostgreSQL (optional) - Production database

Quick Start

1. Clone the Repository

git clone https://github.com/AutoBotSolutions/Opensource-Site-Tracking.git
cd opensource-site-tracking

2. Backend Setup

# Navigate to backend directory
cd backend

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Initialize database
python init_db.py

# Start development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. Frontend Setup

# Navigate to frontend directory (in a new terminal)
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

4. Access the Application

Open your browser and navigate to:

Using Docker Compose

# Clone the repository
git clone https://github.com/AutoBotSolutions/Opensource-Site-Tracking.git
cd opensource-site-tracking

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Services Included

  • Backend: Python Flask application
  • Frontend: Next.js development server
  • Database: PostgreSQL
  • Redis: Caching and session storage

Configuration

Environment Variables

Create a .env file in the backend directory:

# Database Configuration
DATABASE_URL=sqlite:///site_tracking.db
# DATABASE_URL=postgresql://user:password@localhost/dbname

# Application Settings
SECRET_KEY=your-secret-key-here
DEBUG=True
ENVIRONMENT=development

# Analytics Settings
ANALYTICS_ENABLED=True
DATA_RETENTION_DAYS=365

# Security Settings
JWT_SECRET_KEY=your-jwt-secret-key
JWT_EXPIRATION_HOURS=24

Frontend Configuration

Create a .env.local file in the frontend directory:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000

# Application Settings
NEXT_PUBLIC_APP_NAME=Open Source Site Tracking
NEXT_PUBLIC_APP_VERSION=1.0.0

Initial Setup

1. Create Admin User

# Navigate to backend directory
cd backend

# Create admin user
python scripts/create_admin.py --email admin@example.com --password admin123

2. Configure First Project

  1. Log in to the application at http://localhost:3000
  2. Navigate to "Projects" section
  3. Click "Add New Project"
  4. Enter project details:
  5. Project Name: Your project name
  6. Repository URL: GitHub repository URL
  7. Description: Project description
  8. Click "Create Project"

3. Set Up Tracking

Add the tracking script to your website:

<!-- Add to your website's <head> section -->
<script src="http://localhost:8000/tracking.js" data-project-id="your-project-id"></script>

Basic Usage

Dashboard Navigation

  1. Overview: Main dashboard with key metrics
  2. Analytics: Detailed analytics and reports
  3. Projects: Manage tracked projects
  4. Users: User management (admin only)
  5. Settings: Application configuration

Viewing Analytics

  1. Select a project from the dashboard
  2. Choose a time range (today, week, month, custom)
  3. View metrics:
  4. Page views and unique visitors
  5. User engagement statistics
  6. Performance metrics
  7. Geographic distribution

Creating Reports

  1. Navigate to "Analytics" → "Reports"
  2. Click "Create New Report"
  3. Select report type:
  4. Traffic Overview
  5. User Behavior
  6. Performance Analysis
  7. Custom Report
  8. Configure report parameters
  9. Generate and export report

Development Guide

Backend Development

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run with coverage
pytest --cov=app

# Code formatting
black app/
isort app/

# Type checking
mypy app/

Frontend Development

# Install development dependencies
npm install --save-dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Code formatting
npm run format
npm run lint

# Type checking
npm run type-check

Database Migrations

# Create new migration
python scripts/create_migration.py "migration_name"

# Apply migrations
python migrate.py upgrade

# Rollback migration
python migrate.py downgrade

Troubleshooting

Common Issues

Backend Issues

Problem: Backend server won't start

# Check Python version
python --version

# Check virtual environment
which python

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Problem: Database connection errors

# Check database file
ls -la site_tracking.db

# Recreate database
rm site_tracking.db
python init_db.py

Frontend Issues

Problem: Frontend build fails

# Clear node modules
rm -rf node_modules package-lock.json
npm install

# Clear Next.js cache
rm -rf .next
npm run dev

Problem: API connection errors

# Check backend is running
curl http://localhost:8000/health

# Check API URL in .env.local
cat .env.local

Getting Help

Next Steps

Now that you have the application running, consider:

  1. Explore Features: Try out different analytics features
  2. Customize Configuration: Adjust settings for your needs
  3. Add More Projects: Track multiple repositories
  4. Set Up Alerts: Configure notifications for important events
  5. Explore API: Use the REST API for custom integrations
  6. Deploy to Production: Set up a production environment

Resources

Happy tracking! 🚀

auth0 logo