← Back to Table of Contents

Getting Started Guide

Get up and running with Open Source Site Tracking in under 5 minutes. This guide covers the fastest way to start tracking your open source projects.

Prerequisites Quick Start with Docker Manual Setup First Steps Basic Configuration Common Use Cases Troubleshooting Next Steps

Prerequisites

Before you begin, ensure you have the following installed:

Quick Start with Docker (Recommended)

1. Clone and Start

# Clone the repository
git clone https://github.com/AutoBotSolutions/Opensource-Site-Tracking.git
cd opensource-site-tracking
# Start all services with Docker Compose
docker-compose up -d
# Check the status
docker-compose ps

2. Access the Application

3. Create Your First Project

  1. Open http://localhost:3000 in your browser
  2. Click "Sign Up" to create an account
  3. Log in with your new account
  4. Click "Add New Project"
  5. Enter your project details:
    • Name: My First Project
    • Repository URL: https://github.com/yourusername/your-repo
    • Description: My awesome project
  6. Click "Create Project"

4. Add Tracking Code

Add this snippet to your website's <head> section:

<script src="http://localhost:8000/tracking.js" data-project-id="your-project-id"></script>

That's it! You're now tracking your project in real-time.

Manual Setup (Without Docker)

1. Backend Setup

# Clone the repository
git clone https://github.com/AutoBotSolutions/Opensource-Site-Tracking.git
cd opensource-site-tracking/backend
# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Initialize database
python init_db.py
# Start the backend server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

2. Frontend Setup

# In a new terminal
cd opensource-site-tracking/frontend
# Install dependencies
npm install
# Start the frontend server
npm run dev

3. Access the Application

First Steps

Create an Account

  1. Navigate to http://localhost:3000
  2. Click "Sign Up"
  3. Enter your details:
    • Email: your-email@example.com
    • Username: yourusername
    • Password: your-secure-password
  4. Click "Create Account"
  5. Check your email for verification (if enabled)

Set Up Your First Project

  1. Log in to your account
  2. Click "Projects" in the sidebar
  3. Click "Add New Project"
  4. Fill in the project details:
    • Project Name: My Project
    • Repository URL: https://github.com/user/repo
    • Description: Project description
    • Tracking Domain: yourdomain.com (optional)
  5. Click "Create Project"

Add Tracking to Your Website

Copy your project ID and add the tracking script:

<!DOCTYPE html>
<html>
<head>
    <title>Your Website</title>
    <script src="http://localhost:8000/tracking.js" 
            data-project-id="your-project-id"></script>
</head>
<body>
    <h1>Welcome to My Website</h1>
    <!-- Your website content -->
</body>
</html>

View Your Analytics

  1. Go to your project dashboard
  2. Click "Analytics" in the sidebar
  3. You'll see:
    • Page Views: Real-time page view count
    • Unique Visitors: Number of unique visitors
    • Top Pages: Most visited pages
    • Geographic Data: Visitor locations

Basic Configuration

Environment Variables

Create a .env file in the backend directory:

# Database
DATABASE_URL=sqlite:///site_tracking.db
# Security
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key
# Application
DEBUG=True
ENVIRONMENT=development
# Analytics
ANALYTICS_ENABLED=True
DATA_RETENTION_DAYS=365

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

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_APP_NAME=Open Source Site Tracking

Tracking Configuration

Customize tracking behavior:

// Advanced tracking configuration
SiteTracking.init({
  projectId: 'your-project-id',
  tracking: {
    pageViews: true,
    clicks: true,
    scrolls: true,
    forms: true
  },
  privacy: {
    respectDoNotTrack: true,
    anonymizeIp: true
  }
});

Common Use Cases

Blog Analytics

<!-- Add to your blog template -->
<script src="http://localhost:8000/tracking.js" 
        data-project-id="blog-project-id"></script>

E-commerce Tracking

// Track product views
SiteTracking.track('product-view', {
  productId: 'prod-123',
  productName: 'Analytics Pro',
  category: 'software',
  price: 99.99
});
// Track purchases
SiteTracking.track('purchase', {
  orderId: 'order-456',
  products: [
    {
      productId: 'prod-123',
      quantity: 1,
      price: 99.99
    }
  ],
  total: 99.99
});

API Application Tracking

# Track API requests
import requests
def track_api_event(event_type, properties):
    requests.post('http://localhost:8000/api/v1/events/your-project-id', {
        'event_type': event_type,
        'properties': properties
    }, headers={
        'Authorization': 'Bearer your-api-token'
    })
# Usage
track_api_event('api_request', {
    'endpoint': '/api/users',
    'method': 'GET',
    'status_code': 200
})

Troubleshooting

Common Issues

Backend Won't Start

# Check Python version
python --version
# Check virtual environment
which python
# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
# Check database
ls -la site_tracking.db

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

Tracking Not Working

// Enable debug mode
SiteTracking.debug(true);
// Check status
console.log(SiteTracking.getStatus());
// Test tracking
SiteTracking.track('test-event', { test: true });

Database Issues

# Recreate database
rm site_tracking.db
python init_db.py
# Check database connection
python -c "from app.database import get_db; print('Database OK')"

Getting Help

Next Steps

Now that you're up and running, consider:

Explore Features

  1. Real-time Dashboard: Watch live analytics data
  2. Custom Reports: Create detailed reports
  3. User Management: Add team members
  4. API Integration: Use the REST API
  5. Webhooks: Set up event notifications

Advanced Configuration

  1. Production Deployment: Set up production environment
  2. Database Migration: Move to PostgreSQL
  3. SSL Configuration: Enable HTTPS
  4. Custom Domain: Use your own domain
  5. Performance Optimization: Optimize for high traffic

Integration Examples

  1. React Integration: Track React applications
  2. WordPress Plugin: Add to WordPress sites
  3. Mobile Apps: Track mobile applications
  4. Server-side Tracking: Track backend events
  5. Third-party Tools: Integrate with other services
Quick Reference 
# Essential Commands
docker-compose up -d
# Stop services
docker-compose down
# View logs
docker-compose logs -f
# Backend development
cd backend
python -m uvicorn main:app --reload
# Frontend development
cd frontend
npm run dev
Important URLs
  • Application: http://localhost:3000
  • API Documentation: http://localhost:8000/docs
  • Health Check: http://localhost:8000/health
  • API Base: http://localhost:8000/api/v1