Skip to content

Installation Guide

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

🐳 Docker Installation (Production)

Prerequisites

  • Docker and Docker Compose installed
  • Git installed
  • At least 16GB of RAM available (8GB minimum, 16GB recommended)
  • 10GB of free disk space

Note: Docker installation is optimized for production use. For development, use the local installation method below.

Step 1: Clone Repository

git clone https://github.com/assiadialeb/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


# 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 17 (Django database) - Start MongoDB 7.0 (analytics database) - Start Ollama with automatic model initialization (AI for commit classification) - Start the Django application

Note: The first startup may take 5-10 minutes as Ollama automatically downloads the gemma3:4b model (~3.3GB).

Step 4: Verify Services

docker-compose ps

You should see all services with "Up" status.

Step 5: Access the Application

  • Application: http://localhost:8000
  • Admin: http://localhost:8000/admin
  • Ollama API: http://localhost:11435

Note: Database migrations are applied automatically on container startup. Superuser is created automatically by the application.

Step 6: Collect Static Files (Optional)

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

Note: This step is optional for development. Static files are served by Django in debug mode.

Ollama Configuration

The Ollama service is configured with automatic initialization:

  • Automatic Model Download: The gemma3:4b model is automatically downloaded on first startup
  • Persistent Storage: Models are stored in a Docker volume (ollama_data)
  • Health Checks: Automatic health monitoring
  • Custom Image: Uses a custom Docker image based on Ubuntu 22.04 with Ollama pre-installed

Ollama Initialization Process

  1. Container Startup: The container starts with a custom entrypoint script
  2. Server Launch: Ollama server starts in the background
  3. Model Check: The system checks if gemma3:4b model exists
  4. Automatic Download: If not present, downloads the model (~3.3GB)
  5. Ready State: Service becomes healthy and ready for use

Logs Example

🚀 Starting Ollama server...
🚀 Starting Ollama initialization...
⏳ Waiting for Ollama to be ready...
✅ Model gemma3:4b already exists!
🎉 Ollama initialization complete!
🌐 Ollama is ready at http://localhost:11435

🖥️ Local Installation (Development)

Prerequisites

  • Python 3.12+
  • PostgreSQL (recommended) or SQLite
  • MongoDB
  • Valkey (Redis-compatible cache)
  • Git
  • At least 16GB of RAM available (8GB minimum, 16GB recommended)

Note: Local installation is recommended for development and testing. For production deployment, use the Docker installation method above.

Step 1: Clone Repository

git clone https://github.com/assiadialeb/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

Edit the .env file for local development:

# 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_user
POSTGRES_PASSWORD=gitpulse_password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

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

# Valkey/Redis Cache Settings
REDIS_ENABLED=True
REDIS_URL=redis://localhost:6379/1

# Ollama Settings
OLLAMA_HOST=localhost
OLLAMA_PORT=11434

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

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
sudo -u postgres psql -c "ALTER USER gitpulse_user PASSWORD 'gitpulse_password';"

macOS:

brew install postgresql
brew services start postgresql
createdb gitpulse

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

Valkey (Redis-compatible cache)

Ubuntu/Debian:

# Install Valkey
sudo apt update
sudo apt install valkey
sudo systemctl start valkey
sudo systemctl enable valkey

macOS:

# Install Valkey via Homebrew
brew install valkey
brew services start valkey

Windows: Download and install from Valkey website or use Docker:

docker run -d --name valkey -p 6379:6379 valkey/valkey:7.2-alpine

Alternative: Use Redis instead If you prefer to use Redis instead of Valkey:

# Ubuntu/Debian
sudo apt install redis-server

# macOS
brew install redis
brew services start redis

Step 6: Run Migrations

python manage.py makemigrations
python manage.py migrate

Step 7: Install and Configure Ollama

For AI features, you'll need to install Ollama:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama service
ollama serve &

# Download the required model
ollama pull gemma3:4b

Step 8: Start Development Server

python manage.py runserver

Step 9: Access the Application

  • Application: http://localhost:8000
  • Admin: http://localhost:8000/admin
  • Ollama API: http://localhost:11435

Note: Superuser is created automatically by the application.

🔧 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)
  • At least 16GB of RAM available (8GB minimum, 16GB 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/assiadialeb/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 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 (automated in start.sh)
docker-compose exec web python manage.py collectstatic --noinput

Note: The collectstatic command is automatically run during container startup via start.sh. This ensures static files are always collected for production deployment.


### Step 5: Configure Nginx

Create Nginx configuration:

```nginx
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;

    # Serve static files directly
    location /static/ {
        alias /path/to/gitpulse/staticfiles/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    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


## 🚨 Troubleshooting

### Common Issues

**Port conflicts**
```bash
# 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