rentcache/docs/INSTALLATION.md

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
• uv (recommended): Install guide
• 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)

# 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

# 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

# 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:

# 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.

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

PostgreSQL (Production)

1. Install PostgreSQL:

   # 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:

   CREATE DATABASE rentcache;
   CREATE USER rentcache WITH PASSWORD 'your_password';
   GRANT ALL PRIVILEGES ON DATABASE rentcache TO rentcache;
   

3. Update Configuration:

   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:

   # 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:

   REDIS_URL=redis://localhost:6379
   REDIS_ENABLED=true
   

🐳 Docker Installation

Using Docker Compose (Recommended)

1. Create docker-compose.yml:

   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:

   docker-compose up -d
   

Using Docker Directly

1. Build Image:

   docker build -t rentcache .
   

2. Run Container:

   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

# Development
uv run rentcache server --reload

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

2. Verify Installation

# 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

# 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

# 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

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

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

Development Tools Setup

# 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 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

# 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)

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:

[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

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

🔍 Troubleshooting

Common Issues

Database Connection Errors

# 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

# 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

# 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

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

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

Log Analysis

# 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

# 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

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

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

Prometheus Integration

Add to your prometheus.yml:

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:

LOG_FORMAT=json
LOG_LEVEL=INFO

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

🔄 Updates and Maintenance

Updating RentCache

# 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

# 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

# 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 or API Reference for more information.