# Installation Guide

This guide covers all installation methods for RentCache, from development setup to production deployment.

## 📋 Prerequisites

### System Requirements

- **Python**: 3.10 or higher
- **Operating System**: Linux, macOS, or Windows
- **Memory**: Minimum 512MB RAM, 2GB+ recommended for production
- **Storage**: 1GB+ available space (cache database can grow)

### Required Software

- **Python 3.10+**: [Download from python.org](https://www.python.org/downloads/)
- **uv** (recommended): [Install guide](https://docs.astral.sh/uv/getting-started/installation/)
- **Git**: For cloning the repository

### Optional Dependencies

- **Redis**: For enhanced cache performance (production recommended)
- **PostgreSQL**: For production database (SQLite default for development)
- **Docker**: For containerized deployment

## 🚀 Quick Installation

### Method 1: Using uv (Recommended)

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://git.supported.systems/MCP/rentcache.git
cd rentcache

# Install dependencies and create virtual environment
uv sync

# Verify installation
uv run rentcache --help
```

### Method 2: Using pip

```bash
# Clone the repository
git clone https://git.supported.systems/MCP/rentcache.git
cd rentcache

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Verify installation
rentcache --help
```

### Method 3: Production Installation

```bash
# Install from repository
pip install git+https://git.supported.systems/MCP/rentcache.git

# Or install locally built wheel
pip install rentcache-0.1.0-py3-none-any.whl
```

## 🔧 Configuration

### Environment Variables

Create a `.env` file in your project directory:

```env
# Server Configuration
HOST=0.0.0.0
PORT=8000
DEBUG=false
LOG_LEVEL=INFO

# Database Configuration
DATABASE_URL=sqlite+aiosqlite:///./rentcache.db
DATABASE_ECHO=false

# Redis Configuration (Optional)
REDIS_URL=redis://localhost:6379
REDIS_ENABLED=false

# Rentcast API Configuration
RENTCAST_BASE_URL=https://api.rentcast.io
RENTCAST_TIMEOUT=30
RENTCAST_MAX_RETRIES=3

# Cache Settings
DEFAULT_CACHE_TTL=3600
EXPENSIVE_ENDPOINTS_TTL=86400
ENABLE_STALE_WHILE_REVALIDATE=true

# Rate Limiting
ENABLE_RATE_LIMITING=true
GLOBAL_RATE_LIMIT=1000/hour
PER_ENDPOINT_RATE_LIMIT=100/minute

# Security
ALLOWED_HOSTS=*
CORS_ORIGINS=*

# Logging
LOG_FORMAT=json
```

### Configuration Options Explained

| Variable | Description | Default | Production Recommendation |
|----------|-------------|---------|---------------------------|
| `DATABASE_URL` | Database connection string | SQLite local file | PostgreSQL with connection pooling |
| `REDIS_ENABLED` | Enable Redis caching | `false` | `true` for better performance |
| `DEFAULT_CACHE_TTL` | Default cache time in seconds | 3600 (1 hour) | 3600-7200 depending on use case |
| `EXPENSIVE_ENDPOINTS_TTL` | Cache time for costly endpoints | 86400 (24 hours) | 86400-172800 (1-2 days) |
| `GLOBAL_RATE_LIMIT` | Requests per API key per hour | 1000/hour | Adjust based on your Rentcast plan |
| `LOG_LEVEL` | Logging verbosity | INFO | INFO (WARNING for high-traffic) |

## 🗄️ Database Setup

### SQLite (Development)

SQLite is the default and requires no additional setup. The database file will be created automatically on first run.

```bash
# Database will be created at ./rentcache.db
rentcache server
```

### PostgreSQL (Production)

1. **Install PostgreSQL**:
   ```bash
   # Ubuntu/Debian
   sudo apt-get install postgresql postgresql-contrib
   
   # macOS
   brew install postgresql
   
   # Or use Docker
   docker run -d --name postgres \
     -e POSTGRES_DB=rentcache \
     -e POSTGRES_USER=rentcache \
     -e POSTGRES_PASSWORD=your_password \
     -p 5432:5432 \
     postgres:15
   ```

2. **Create Database**:
   ```sql
   CREATE DATABASE rentcache;
   CREATE USER rentcache WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE rentcache TO rentcache;
   ```

3. **Update Configuration**:
   ```env
   DATABASE_URL=postgresql://rentcache:your_password@localhost:5432/rentcache
   ```

### Redis Setup (Optional)

Redis significantly improves cache performance, especially for high-traffic applications.

1. **Install Redis**:
   ```bash
   # Ubuntu/Debian
   sudo apt-get install redis-server
   
   # macOS
   brew install redis
   
   # Or use Docker
   docker run -d --name redis -p 6379:6379 redis:7-alpine
   ```

2. **Enable in Configuration**:
   ```env
   REDIS_URL=redis://localhost:6379
   REDIS_ENABLED=true
   ```

## 🐳 Docker Installation

### Using Docker Compose (Recommended)

1. **Create `docker-compose.yml`**:
   ```yaml
   services:
     rentcache:
       build: .
       ports:
         - "8000:8000"
       environment:
         - DATABASE_URL=postgresql://rentcache:password@db:5432/rentcache
         - REDIS_URL=redis://redis:6379
         - REDIS_ENABLED=true
       depends_on:
         - db
         - redis
       volumes:
         - ./data:/app/data
   
     db:
       image: postgres:15
       environment:
         POSTGRES_DB: rentcache
         POSTGRES_USER: rentcache
         POSTGRES_PASSWORD: password
       volumes:
         - postgres_data:/var/lib/postgresql/data
   
     redis:
       image: redis:7-alpine
       volumes:
         - redis_data:/data
   
   volumes:
     postgres_data:
     redis_data:
   ```

2. **Start Services**:
   ```bash
   docker-compose up -d
   ```

### Using Docker Directly

1. **Build Image**:
   ```bash
   docker build -t rentcache .
   ```

2. **Run Container**:
   ```bash
   docker run -d --name rentcache \
     -p 8000:8000 \
     -e DATABASE_URL=sqlite+aiosqlite:///./data/rentcache.db \
     -v $(pwd)/data:/app/data \
     rentcache
   ```

## 🔐 Initial Setup

### 1. Start the Server

```bash
# Development
uv run rentcache server --reload

# Production
uv run rentcache server --host 0.0.0.0 --port 8000
```

### 2. Verify Installation

```bash
# Check health
curl http://localhost:8000/health

# Expected response
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0",
  "database": "healthy",
  "cache_backend": "sqlite",
  "active_keys": 0,
  "total_cache_entries": 0
}
```

### 3. Create Your First API Key

```bash
# Replace YOUR_RENTCAST_API_KEY with your actual Rentcast API key
uv run rentcache create-key my_app YOUR_RENTCAST_API_KEY

# Or with custom limits
uv run rentcache create-key production_app YOUR_RENTCAST_API_KEY \
  --daily-limit 5000 \
  --monthly-limit 100000 \
  --expires 2024-12-31
```

### 4. Test API Access

```bash
# Test property search (replace YOUR_RENTCAST_API_KEY)
curl -H "Authorization: Bearer YOUR_RENTCAST_API_KEY" \
  "http://localhost:8000/api/v1/properties?city=Austin&state=TX&limit=5"

# Check cache performance
curl http://localhost:8000/metrics
```

## 🛠️ Development Setup

### Installing Development Dependencies

```bash
# Install with development dependencies
uv sync --all-extras

# Or with pip
pip install -e ".[dev]"
```

### Development Tools Setup

```bash
# Install pre-commit hooks (optional but recommended)
pre-commit install

# Run tests
uv run pytest

# Format code
uv run black src tests
uv run ruff check src tests --fix

# Type checking
uv run mypy src
```

### Development Environment

```env
# .env for development
DEBUG=true
LOG_LEVEL=DEBUG
DATABASE_ECHO=true
CORS_ORIGINS=http://localhost:3000,http://localhost:8080
```

## 🚀 Production Deployment

### System Requirements

- **CPU**: 2+ cores
- **Memory**: 4GB+ RAM
- **Storage**: 10GB+ SSD
- **Network**: 100Mbps+ bandwidth

### Production Configuration

```env
# Production .env
DEBUG=false
LOG_LEVEL=INFO
LOG_FORMAT=json

# Use PostgreSQL
DATABASE_URL=postgresql://user:pass@db-host:5432/rentcache

# Enable Redis
REDIS_URL=redis://redis-host:6379
REDIS_ENABLED=true

# Security
ALLOWED_HOSTS=yourdomain.com,api.yourdomain.com
CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com

# Performance
DEFAULT_CACHE_TTL=7200
EXPENSIVE_ENDPOINTS_TTL=172800
```

### Reverse Proxy Setup (Nginx)

```nginx
server {
    listen 80;
    server_name api.yourdomain.com;
    
    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;
    }
}
```

### Process Management (systemd)

Create `/etc/systemd/system/rentcache.service`:

```ini
[Unit]
Description=RentCache API Server
After=network.target

[Service]
Type=exec
User=rentcache
Group=rentcache
WorkingDirectory=/opt/rentcache
Environment=PATH=/opt/rentcache/.venv/bin
ExecStart=/opt/rentcache/.venv/bin/rentcache server --host 0.0.0.0 --port 8000
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
# Enable and start service
sudo systemctl enable rentcache
sudo systemctl start rentcache
sudo systemctl status rentcache
```

## 🔍 Troubleshooting

### Common Issues

#### Database Connection Errors

```bash
# Check database file permissions
ls -la rentcache.db

# Check PostgreSQL connection
psql postgresql://user:pass@host:5432/dbname

# Reset database
rm rentcache.db  # SQLite only
uv run rentcache server  # Will recreate tables
```

#### Redis Connection Issues

```bash
# Test Redis connection
redis-cli ping

# Check Redis configuration
redis-cli config get '*'

# Disable Redis temporarily
echo "REDIS_ENABLED=false" >> .env
```

#### Port Already in Use

```bash
# Find process using port 8000
lsof -i :8000

# Kill process
kill -9 <PID>

# Or use different port
uv run rentcache server --port 8001
```

#### Permission Denied

```bash
# Fix file permissions
chmod +x $(which rentcache)

# Fix data directory permissions
sudo chown -R $USER:$USER ./data
```

### Log Analysis

```bash
# View logs in development
uv run rentcache server --log-level DEBUG

# Production log analysis
tail -f /var/log/rentcache/access.log | jq '.'

# Filter for errors
tail -f /var/log/rentcache/access.log | jq 'select(.level == "ERROR")'
```

### Performance Issues

```bash
# Check cache hit ratio
uv run rentcache stats

# Monitor database size
du -h rentcache.db

# Check memory usage
ps aux | grep rentcache

# Monitor request patterns
curl http://localhost:8000/metrics | jq '.top_endpoints'
```

## 📊 Monitoring Setup

### Health Check Endpoint

```bash
# Basic health check
curl http://localhost:8000/health

# Detailed metrics
curl http://localhost:8000/metrics
```

### Prometheus Integration

Add to your `prometheus.yml`:

```yaml
scrape_configs:
  - job_name: 'rentcache'
    static_configs:
      - targets: ['localhost:8000']
    metrics_path: /metrics
    scrape_interval: 30s
```

### Log Aggregation

For centralized logging, configure structured JSON output:

```env
LOG_FORMAT=json
LOG_LEVEL=INFO
```

Then forward logs to your preferred system (ELK, Splunk, etc.).

## 🔄 Updates and Maintenance

### Updating RentCache

```bash
# Pull latest changes
git pull origin main

# Install updated dependencies
uv sync

# Run database migrations (if any)
uv run alembic upgrade head

# Restart service
sudo systemctl restart rentcache
```

### Backup Procedures

```bash
# Backup SQLite database
cp rentcache.db rentcache.db.backup

# Backup PostgreSQL
pg_dump rentcache > rentcache_backup.sql

# Backup configuration
cp .env .env.backup
```

### Maintenance Tasks

```bash
# Clear old cache entries (older than 7 days)
uv run rentcache clear-cache --older-than 168

# Check system health
uv run rentcache health

# View usage statistics
uv run rentcache stats --days 30
```

---

Need help? Check the [Usage Guide](USAGE.md) or [API Reference](API.md) for more information.