merchbay/DEPLOYMENT_GUIDE.md

# Google Cloud Run Deployment Guide for Merchbay Laravel Application

This guide will help you deploy your Laravel 5 application to Google Cloud Run using the provided `cloudbuild.yaml` configuration.

## Prerequisites

1. **Google Cloud Project**: Ensure you have a Google Cloud Project with billing enabled
2. **APIs Enabled**: Enable the following APIs:
   - Cloud Build API
   - Cloud Run API
   - Container Registry API (or Artifact Registry API)
   - Cloud SQL API (if using Cloud SQL)
   - Secret Manager API (recommended for secrets)

3. **gcloud CLI**: Install and configure the Google Cloud CLI

## Pre-deployment Setup

### 1. Create Cloud SQL Instance (Recommended)

```bash
# Create MySQL instance
gcloud sql instances create merchbay-db \
    --database-version=MYSQL_8_0 \
    --tier=db-f1-micro \
    --region=us-central1

# Create database
gcloud sql databases create merchbay --instance=merchbay-db

# Create user
gcloud sql users create laravel_user \
    --instance=merchbay-db \
    --password=YOUR_SECURE_PASSWORD
```

### 2. Store Secrets in Secret Manager

```bash
# Application key (generate a new one)
echo "base64:$(openssl rand -base64 32)" | gcloud secrets create APP_KEY --data-file=-

# Database password
echo "YOUR_DB_PASSWORD" | gcloud secrets create DB_PASSWORD --data-file=-

# PayPal secrets
echo "YOUR_PAYPAL_LIVE_SECRET" | gcloud secrets create PAYPAL_LIVE_SECRET --data-file=-
echo "YOUR_PAYPAL_SANDBOX_SECRET" | gcloud secrets create PAYPAL_SANDBOX_SECRET --data-file=-

# Mail password
echo "YOUR_MAIL_PASSWORD" | gcloud secrets create MAIL_PASSWORD --data-file=-
```

### 3. Update cloudbuild.yaml Variables

Update the substitution variables in `cloudbuild.yaml`:

```yaml
substitutions:
  _SERVICE_NAME: 'merchbay-laravel'
  _REGION: 'us-central1'  # Change to your preferred region
  _CLOUDSQL_INSTANCE: 'YOUR_PROJECT_ID:us-central1:merchbay-db'
  _DB_DATABASE: 'merchbay'
  _DB_USERNAME: 'laravel_user'
  # ... other variables
```

## Deployment Steps

### 1. Set up Cloud Build Trigger

```bash
# Connect your repository to Cloud Build
gcloud builds triggers create github \
    --repo-name=YOUR_REPO_NAME \
    --repo-owner=YOUR_GITHUB_USERNAME \
    --branch-pattern="^main$" \
    --build-config=cloudbuild.yaml

# Or trigger manually
gcloud builds submit --config=cloudbuild.yaml .
```

### 2. Manual Deployment (Alternative)

```bash
# Set your project ID
export PROJECT_ID=your-project-id

# Build and deploy
gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=_PROJECT_ID=$PROJECT_ID,_SERVICE_NAME=merchbay-laravel
```

## Post-deployment Tasks

### 1. Run Database Migrations

```bash
# Create a one-time job for migrations
gcloud run jobs create laravel-migrate \
    --image=gcr.io/$PROJECT_ID/merchbay-laravel:latest \
    --region=us-central1 \
    --set-env-vars="APP_ENV=production" \
    --set-cloudsql-instances=$PROJECT_ID:us-central1:merchbay-db \
    --command="php" \
    --args="artisan,migrate,--force" \
    --max-retries=1

# Execute the migration
gcloud run jobs execute laravel-migrate --region=us-central1 --wait
```

### 2. Set up Custom Domain (Optional)

```bash
# Map custom domain
gcloud run domain-mappings create \
    --service=merchbay-laravel \
    --domain=your-domain.com \
    --region=us-central1
```

### 3. Configure Load Balancer and CDN (Optional)

For better performance, consider setting up:
- Cloud Load Balancer
- Cloud CDN for static assets
- Cloud Storage for file uploads

## Environment Variables Reference

The following environment variables are configured in the Cloud Run service:

### Application Settings
- `APP_ENV=production`
- `APP_DEBUG=false`
- `APP_KEY` (from Secret Manager)

### Database Settings
- `DB_HOST=127.0.0.1` (Cloud SQL Proxy)
- `DB_DATABASE=merchbay`
- `DB_USERNAME=laravel_user`
- `DB_PASSWORD` (from Secret Manager)

### Cache & Session
- `CACHE_DRIVER=redis` (requires Redis setup)
- `SESSION_DRIVER=redis`
- `QUEUE_DRIVER=database`

### PayPal Configuration
- `PAYPAL_MODE=live` (or 'sandbox' for testing)
- `PAYPAL_LIVE_CLIENT_ID`
- `PAYPAL_LIVE_SECRET`
- `PAYPAL_SANDBOX_CLIENT_ID`
- `PAYPAL_SANDBOX_SECRET`

### Mail Configuration
- `MAIL_DRIVER=smtp`
- `MAIL_HOST`
- `MAIL_PORT`
- `MAIL_USERNAME`
- `MAIL_PASSWORD`

## Monitoring and Logging

### Enable Application Insights

```bash
# Enable Cloud Logging
gcloud logging sinks create laravel-logs \
    bigquery.googleapis.com/projects/$PROJECT_ID/datasets/app_logs
```

### Set up Uptime Monitoring

```bash
# Create uptime check
gcloud alpha monitoring uptime create \
    --display-name="Merchbay Laravel App" \
    --http-check-path="/" \
    --hostname=your-service-url.run.app
```

## Troubleshooting

### Common Issues

1. **502 Bad Gateway**: Check logs with `gcloud run services logs read merchbay-laravel`
2. **Database Connection Issues**: Verify Cloud SQL instance and VPC configuration
3. **Memory Issues**: Increase memory allocation in cloudbuild.yaml
4. **Timeout Issues**: Increase timeout and check for long-running operations

### Debugging Commands

```bash
# View service logs
gcloud run services logs read merchbay-laravel --region=us-central1

# Get service details
gcloud run services describe merchbay-laravel --region=us-central1

# Check revisions
gcloud run revisions list --service=merchbay-laravel --region=us-central1
```

## Security Considerations

1. **Use Secret Manager** for all sensitive data
2. **Enable VPC** for database connections
3. **Configure IAM** with least privilege principle
4. **Enable Cloud Armor** for DDoS protection
5. **Use HTTPS** with managed SSL certificates
6. **Regular Updates** for dependencies and base images

## Cost Optimization

1. **Set Min Instances to 0** for cost savings
2. **Use Appropriate CPU/Memory** settings
3. **Implement Caching** (Redis/Memcached)
4. **Optimize Images** and use multi-stage builds
5. **Monitor Usage** with Cloud Monitoring

## Support

For issues specific to:
- **Cloud Run**: Check [Cloud Run documentation](https://cloud.google.com/run/docs)
- **Laravel**: Check [Laravel documentation](https://laravel.com/docs)
- **PayPal Integration**: Check [PayPal developer documentation](https://developer.paypal.com/)