rothbard/terraform/README.md

# Rothbard Law Group - Terraform Deployment

This Terraform configuration deploys the Rothbard Law Group client portal to Google Cloud Platform with Firebase backend.

## Architecture Overview

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Firebase App  │    │   Firestore     │    │  Cloud Run      │
│   (Client Auth) │◄──►│   (User Data)   │◄──►│  (Flask App)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
                                              ┌─────────────────┐
                                              │  Filevine API   │
                                              │  (Case Data)    │
                                              └─────────────────┘
```

## Hosting Options

### 1. Cloud Run (Recommended)
- **Best for production use**
- Container-based deployment
- Scales from 0 to N instances
- Cost-effective (pay-per-use)
- Full control over environment

### 2. App Engine
- Platform-as-a-service
- Built-in scaling
- Slightly more restrictive
- Good for simpler deployments

## Prerequisites

1. **Google Cloud SDK**
   ```bash
   curl https://sdk.cloud.google.com | bash
   gcloud init
   ```

2. **Terraform**
   ```bash
   # macOS
   brew install terraform

   # Linux
   sudo apt-get install terraform
   ```

3. **Docker** (for Cloud Run)
   ```bash
   # macOS
   brew install docker

   # Linux
   sudo apt-get install docker.io
   ```

## Setup Instructions

### 1. Configure Terraform Variables

Copy the example variables file:
```bash
cp terraform.tfvars.example terraform.tfvars
```

Edit `terraform.tfvars` with your values:
```hcl
gcp_project_id = "your-gcp-project-id"
domain_name = "rothbard.yourdomain.com"
hosting_option = "cloud_run"  # or "app_engine"
```

### 2. Set Environment Variables

Create a `.env` file for sensitive data:
```bash
# Flask Configuration
FLASK_SECRET_KEY=your-super-secret-key

# Firebase Configuration
FIREBASE_API_KEY=your-firebase-api-key
FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
FIREBASE_PROJECT_ID=your-gcp-project-id
FIREBASE_APP_ID=your-firebase-app-id

# Service Account (optional - can use gcloud auth)
FIREBASE_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'

# Filevine API Configuration
FILEVINE_CLIENT_ID=your-filevine-client-id
FILEVINE_CLIENT_SECRET=your-filevine-client-secret
FILEVINE_PERSONAL_ACCESS_TOKEN=your-filevine-pat
FILEVINE_ORG_ID=your-filevine-org-id
FILEVINE_USER_ID=your-filevine-user-id
```

### 3. Deploy with Cloud Run (Recommended)

#### Step 1: Build and Push Docker Image
```bash
# Set your project ID
export PROJECT_ID=your-gcp-project-id

# Build the Docker image
docker build -t gcr.io/$PROJECT_ID/rothbard-portal:latest .

# Push to Google Container Registry
docker push gcr.io/$PROJECT_ID/rothbard-portal:latest
```

#### Step 2: Deploy Infrastructure
```bash
cd terraform

# Initialize Terraform
terraform init

# Plan the deployment
terraform plan

# Apply the changes
terraform apply
```

#### Step 3: Update Container Image Variable
After the first deployment, update your `terraform.tfvars`:
```hcl
container_image = "gcr.io/your-gcp-project-id/rothbard-portal:latest"
```

Then run `terraform apply` again.

### 4. Deploy with App Engine

#### Step 1: Create Source Package
```bash
# Copy app files and create zip
cp app.py requirements.txt templates/ app-engine/
cd app-engine
zip -r ../app-source.zip .
cd ..
```

#### Step 2: Deploy Infrastructure
```bash
cd terraform

# Set hosting option to app_engine
# Edit terraform.tfvars: hosting_option = "app_engine"

# Initialize and apply
terraform init
terraform plan
terraform apply
```

## Post-Deployment Setup

### 1. Firebase Configuration

After deployment, you'll need to:

1. **Configure Firebase Authentication**:
   - Go to Firebase Console → Authentication
   - Enable Email/Password provider
   - Add your domain to authorized domains

2. **Set up Firestore Rules**:
   ```javascript
   rules_version = '2';
   service cloud.firestore {
     match /databases/{database}/documents {
       match /users/{userId} {
         allow read, write: if request.auth != null && request.auth.uid == userId;
       }
     }
   }
   ```

### 2. Enable Users

Users need to be manually enabled in Firestore:

```javascript
// In Firebase Console → Firestore Database
// Create document in collection 'users' with document ID = Firebase UID
{
  enabled: true,
  caseEmail: "user@example.com",  // This filters Filevine projects
  name: "Client Name"
}
```

### 3. Custom Domain (Optional)

For Cloud Run with custom domain:

```bash
# Map your domain to the Cloud Run service
gcloud run services add-iam-policy-binding rothbard-portal-service \
  --member="allUsers" \
  --role="roles/run.invoker"

# Set up domain mapping
gcloud run domain-mappings create \
  --domain=rothbard.yourdomain.com \
  --service=rothbard-portal-service
```

## Monitoring and Maintenance

### View Logs
```bash
# Cloud Run logs
gcloud logs read "resource.type=cloud_run_revision" --limit 50

# App Engine logs
gcloud app logs tail -s default
```

### Scale Configuration

For Cloud Run, you can adjust scaling in `terraform/modules/cloud_run/main.tf`:
```hcl
metadata {
  annotations = {
    "autoscaling.knative.dev/maxScale" = "10"  # Max instances
    "autoscaling.knative.dev/minScale" = "1"   # Min instances
  }
}
```

### Updates

To update the application:

1. **Cloud Run**: Build and push new Docker image, then update the `container_image` variable
2. **App Engine**: Update source code, create new zip, and redeploy

## Costs

### Cloud Run (Recommended)
- **Free tier**: 180,000 vCPU-seconds, 360,000 GiB-seconds memory per month
- **Beyond free tier**: ~$0.000024 per vCPU-second, $0.0000025 per GiB-second
- **Typical cost**: $5-20/month for low traffic client portal

### App Engine
- **Free tier**: 28 instance-hours per day
- **Beyond free tier**: ~$0.05 per instance-hour
- **Typical cost**: $10-50/month depending on traffic

### Firebase
- **Spark plan**: Free for most use cases
- **Blaze plan**: Pay-as-you-go for high usage
- **Typical cost**: $0-25/month depending on authentication usage

## Security Considerations

1. **Service Account**: Minimal permissions granted (Firestore and Firebase Admin)
2. **Secret Management**: Sensitive data stored in Secret Manager
3. **HTTPS**: All traffic encrypted with TLS
4. **Authentication**: Firebase ID tokens verified server-side
5. **Access Control**: User access controlled through Firestore profiles

## Troubleshooting

### Common Issues

1. **Build failures**: Check Dockerfile and requirements.txt
2. **Permission errors**: Verify service account has correct IAM roles
3. **Firebase connection**: Ensure service account key is properly formatted
4. **CORS errors**: Configure Firebase Auth domain correctly

### Debug Commands

```bash
# Check Cloud Run service status
gcloud run services describe rothbard-portal-service

# Test service locally
docker run -p 5000:5000 gcr.io/$PROJECT_ID/rothbard-portal:latest

# Check Terraform state
terraform show
```

## Support

For issues with:
- **Terraform deployment**: Check Terraform logs and state
- **Cloud Run**: View Cloud Run logs in Google Console
- **Firebase**: Check Firebase Console for configuration issues
- **Application**: Review Flask application logs