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)

# 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

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

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

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

# 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

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

# 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

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

Set up Uptime Monitoring

# 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

# 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
• Laravel: Check Laravel documentation
• PayPal Integration: Check PayPal developer documentation