MCP/rentcache
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
rentcache/docs/INSTALLATION.md
Ryan Malloy 825f0a9224 Add comprehensive documentation and update repository URLs 
- Complete README.md with installation, usage, and cost savings examples
- Detailed INSTALLATION.md guide for all deployment scenarios
- Comprehensive USAGE.md with CLI and API examples
- Complete API.md reference for all endpoints
- Update pyproject.toml with correct git.supported.systems URLs
- Highlight 70-90% cost savings throughout documentation
- Professional documentation structure with cross-references
2025-09-09 17:45:20 -06:00

592 lines
12 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink