Installation Guide - Open Source Site Tracking

System Requirements

Minimum Requirements

Component	Minimum	Recommended
CPU	2 cores	4 cores
RAM	2GB	4GB
Storage	20GB	50GB
OS	Linux/macOS/Windows	Ubuntu 20.04+

Software Requirements

Python 3.8+: Backend development environment
Node.js 16+: Frontend development environment
Docker 20.10+: Containerization (recommended)
Git 2.25+: Version control system
PostgreSQL 12+: Database (recommended)

Docker Installation

Quick Start with Docker Compose

1. Install Docker

# Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# macOS (using Homebrew)
brew install docker
brew install docker-compose
# Windows
# Download Docker Desktop from https://docker.com

2. Clone Repository

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

3. Start Services

# Start all services
docker-compose up -d
# Check status
docker-compose ps
# View logs
docker-compose logs -f

4. Access Application

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Documentation: http://localhost:8000/docs

Docker Compose Configuration

version: '3.8'
services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/site_tracking
      - SECRET_KEY=your-secret-key
    depends_on:
      - db
    volumes:
      - ./backend:/app
      - ./logs:/app/logs
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:8000
    depends_on:
      - backend
    volumes:
      - ./frontend:/app
  db:
    image: postgres:13
    environment:
      - POSTGRES_DB=site_tracking
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

Manual Installation

Backend Installation

1. Install Python Dependencies

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
# Upgrade pip
pip install --upgrade pip
# Install dependencies
cd backend
pip install -r requirements.txt

2. Install System Dependencies

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3-dev python3-pip postgresql-server-dev-all build-essential
# CentOS/RHEL
sudo yum install python3-devel postgresql-devel gcc
# macOS
brew install postgresql

3. Initialize Database

# Create database
sudo -u postgres createdb site_tracking
# Run database migrations
python init_db.py

4. Start Backend

# Development server
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
# Production server
gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:8000

Frontend Installation

1. Install Node.js Dependencies

# Install Node.js (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
# Install dependencies
cd frontend
npm install

2. Start Frontend

# Development server
npm run dev
# Production build
npm run build
# Production server
npm start

Database Setup

PostgreSQL Setup

1. Install PostgreSQL

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib
# CentOS/RHEL
sudo yum install postgresql-server postgresql-contrib
sudo postgresql-setup initdb
# macOS
brew install postgresql
brew services start postgresql

2. Configure PostgreSQL

# Switch to postgres user
sudo -i postgres
# Create database
createdb site_tracking
# Create user
createuser site_tracking_user
psql -c "ALTER USER site_tracking_user PASSWORD 'your_password';"
# Grant privileges
psql -c "GRANT ALL PRIVILEGES ON DATABASE site_tracking TO site_tracking_user;"

3. Update Configuration

# Update .env file
DATABASE_URL=postgresql://site_tracking_user:your_password@localhost:5432/site_tracking

SQLite Setup

1. Install SQLite

# Ubuntu/Debian
sudo apt-get install sqlite3 libsqlite3-dev
# CentOS/RHEL
sudo yum install sqlite sqlite-devel
# macOS
brew install sqlite

2. Initialize Database

# Update .env file
DATABASE_URL=sqlite:///site_tracking.db
# Initialize database
python init_db.py

Configuration

Environment Variables

Create .env file

# Database Configuration
DATABASE_URL=postgresql://site_tracking_user:password@localhost:5432/site_tracking
# Security Configuration
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key
# Application Configuration
DEBUG=False
ENVIRONMENT=production
# Email Configuration
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
# Analytics Configuration
ANALYTICS_ENABLED=True
DATA_RETENTION_DAYS=365

Configuration Files

# backend/config.py
import os
class Config:
    DATABASE_URL = os.environ.get('DATABASE_URL', 'sqlite:///site_tracking.db')
    SECRET_KEY = os.environ.get('SECRET_KEY', 'dev-secret-key')
    JWT_SECRET_KEY = os.environ.get('JWT_SECRET_KEY', 'jwt-secret-key')
    DEBUG = os.environ.get('DEBUG', 'False').lower() == 'true'
    ENVIRONMENT = os.environ.get('ENVIRONMENT', 'development')
class DevelopmentConfig(Config):
    DEBUG = True
class ProductionConfig(Config):
    DEBUG = False

Verification

Health Checks

Backend Health Check

# Check backend health
curl http://localhost:8000/health
# Expected response
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Frontend Health Check

# Check frontend health
curl http://localhost:3000
# Expected response

Database Connection Test

# Test database connection
python -c "from app.database import get_db; print('Database OK')"
# PostgreSQL test
psql -h localhost -U site_tracking_user -d site_tracking -c "SELECT 1;"
# SQLite test
sqlite3 site_tracking.db "SELECT 1;"

API Test

# Test API endpoint
curl http://localhost:8000/api/v1/projects
# Expected response
{
  "projects": [],
  "total": 0,
  "page": 1,
  "per_page": 20
}

Troubleshooting

Common Issues

Backend Issues

Problem: Backend won't start

# Check Python version
python --version
# Check virtual environment
which python
# Check dependencies
pip list
# Check configuration
python -c "from config import Config; print('Config OK')"

Problem: Database connection error

# Check database service
sudo systemctl status postgresql
# Check database connectivity
psql -h localhost -U postgres -l
# Check connection string
echo $DATABASE_URL

Problem: Port already in use

# Check port usage
netstat -tulpn | grep :8000
# Kill process using port
sudo kill -9 PID
# Use different port
python -m uvicorn main:app --port 8001

Frontend Issues

Problem: Frontend build fails

# Clear cache
rm -rf node_modules package-lock.json
npm install
# Clear Next.js cache
rm -rf .next
npm run dev

Problem: API connection error

# Check backend is running
curl http://localhost:8000/health
# Check API URL in .env.local
cat .env.local | grep API_URL
# Check CORS configuration
curl -H "Origin: http://localhost:3000" http://localhost:8000/api/v1/projects

Docker Issues

Problem: Container won't start

# Check Docker status
docker --version
docker-compose --version
# Check images
docker images
# Rebuild containers
docker-compose down
docker-compose up -d --build

Problem: Database connection in container

# Check container logs
docker-compose logs backend
# Check network
docker network ls
docker network inspect opensource-site-tracking_default
# Test connection from container
docker-compose exec backend python -c "from app.database import get_db; print('OK')"

Getting Help

Documentation: Check the full documentation
Issues: Report issues on GitHub
Discussions: Ask questions in GitHub Discussions
Community: Join our Discord community

Installation Complete!

Congratulations! You have successfully installed the Open Source Site Tracking platform. You can now:

Access the application at http://localhost:3000
Create your first project
Start tracking analytics
Explore the API documentation

For next steps, check out the Getting Started Guide.