Skip to content

Installation Guide

This guide covers all installation methods for GitPulse, from Docker to local development setup.

Prerequisites

  • Docker and Docker Compose installed
  • Git installed
  • At least 4GB of RAM available
  • 10GB of free disk space

Step 1: Clone Repository

git clone https://github.com/gitpulse/gitpulse.git
cd GitPulse

Step 2: Environment Configuration

Create a .env file at the project root:

cp env.example .env

Edit the .env file according to your needs:

# Django Settings
DEBUG=True
SECRET_KEY=your-secret-key-here
ALLOWED_HOSTS=localhost,127.0.0.1

# Database Settings
POSTGRES_DB=gitpulse
POSTGRES_USER=gitpulse
POSTGRES_PASSWORD=gitpulse_password
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# MongoDB Settings
MONGODB_HOST=mongodb
MONGODB_PORT=27017
MONGODB_NAME=gitpulse

# Redis Settings
REDIS_HOST=redis
REDIS_PORT=6379

# Ollama Settings
OLLAMA_HOST=ollama
OLLAMA_PORT=11434

# GitHub OAuth (optional for development)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Step 3: Start Services

# Build and start all services
docker-compose up -d --build

This command will: - Build the Docker image for the application - Start PostgreSQL (Django database) - Start MongoDB (analytics database) - Start Redis (cache) - Start Ollama (AI for commit classification) - Start the Django application

Step 4: Verify Services

docker-compose ps

You should see all services with "Up" status.

Step 5: Initialize Database

# Create Django migrations
docker-compose exec web python manage.py makemigrations

# Apply migrations
docker-compose exec web python manage.py migrate

# Create superuser
docker-compose exec web python manage.py createsuperuser

Step 6: Collect Static Files

docker-compose exec web python manage.py collectstatic --noinput

Step 7: Access the Application

  • Application: http://localhost:8000
  • Admin: http://localhost:8000/admin

🖥️ Local Installation

Prerequisites

  • Python 3.12+
  • PostgreSQL (recommended) or SQLite
  • MongoDB
  • Git

Step 1: Clone Repository

git clone https://github.com/gitpulse/gitpulse.git
cd GitPulse

Step 2: Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment

cp env.example .env
# Edit .env with your database settings

Step 5: Install and Configure Databases

PostgreSQL

Ubuntu/Debian:

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo -u postgres createuser gitpulse_user
sudo -u postgres createdb gitpulse_new
sudo -u postgres psql -c "ALTER USER gitpulse_user PASSWORD 'gitpulse_password';"

macOS:

brew install postgresql
brew services start postgresql
createdb gitpulse_new

Windows: Download and install from PostgreSQL website

MongoDB

Ubuntu/Debian:

sudo apt update
sudo apt install mongodb
sudo systemctl start mongodb
sudo systemctl enable mongodb

macOS:

brew install mongodb-community
brew services start mongodb-community

Windows: Download and install from MongoDB website

Step 6: Run Migrations

python manage.py makemigrations
python manage.py migrate

Step 7: Create Superuser

python manage.py createsuperuser

Step 8: Start Development Server

python manage.py runserver

Step 9: Access the Application

  • Application: http://localhost:8000
  • Admin: http://localhost:8000/admin

🔧 Development Setup

Additional Development Tools

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

# Install pre-commit hooks
pre-commit install

# Install additional tools
pip install black isort flake8 mypy

Database Setup for Development

# Create test database
createdb gitpulse_test

# Run tests
python manage.py test

# Load sample data (if available)
python manage.py loaddata sample_data.json

🚀 Production Installation

Prerequisites

  • Linux server (Ubuntu 20.04+ recommended)
  • Docker and Docker Compose
  • Nginx (for reverse proxy)
  • SSL certificate (Let's Encrypt recommended)

Step 1: Server Setup

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Step 2: Clone and Configure

git clone https://github.com/gitpulse/gitpulse.git
cd GitPulse
cp env.example .env

Step 3: Production Configuration

Edit .env for production:

DEBUG=False
SECRET_KEY=your-very-long-and-random-secret-key
ALLOWED_HOSTS=your-domain.com,www.your-domain.com

# Use external databases for production
POSTGRES_HOST=your-postgres-host
POSTGRES_PASSWORD=very-secure-password
MONGODB_HOST=your-mongodb-host

Step 4: Deploy

# Build and start
docker-compose -f docker-compose.prod.yml up -d --build

# Run migrations
docker-compose exec web python manage.py migrate

# Create superuser
docker-compose exec web python manage.py createsuperuser

# Collect static files
docker-compose exec web python manage.py collectstatic --noinput

Step 5: Configure Nginx

Create Nginx configuration:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🔐 Security Considerations

Production Security

  1. Use strong passwords env POSTGRES_PASSWORD=very-long-random-password-with-special-chars

  2. Disable debug mode env DEBUG=False

  3. Use HTTPS

  4. Configure SSL certificates

  5. Redirect HTTP to HTTPS

  6. Restrict database access

  7. Use firewall rules

  8. Configure database authentication

  9. Regular updates

  10. Keep dependencies updated
  11. Monitor security advisories

Environment Variables Security

# Set file permissions
chmod 600 .env

# Use environment-specific files
cp env.example .env.production

🚨 Troubleshooting

Common Issues

Port conflicts

# Check what's using port 8000
lsof -i :8000

# Kill the process
kill -9 <PID>

Database connection issues

# Test PostgreSQL
psql -h localhost -U gitpulse_user -d gitpulse_new

# Test MongoDB
mongo localhost:27017/gitpulse

Permission issues

# Fix file permissions
chmod +x manage.py
chmod 600 .env

Docker issues

# Clean up Docker
docker system prune -a

# Rebuild containers
docker-compose down
docker-compose up -d --build

Getting Help

📚 Next Steps