Re_Backend/GCS_CONFIGURATION_GUIDE.md

GCS (Google Cloud Storage) Configuration Guide

Overview

All document uploads (workflow documents, work note attachments) are now configured to use Google Cloud Storage (GCS) instead of local file storage.

Configuration Steps

1. Update .env File

Add or update the following environment variables in your .env file:

# Cloud Storage (GCP)
GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_BUCKET_NAME=your-bucket-name-here
GCP_KEY_FILE=./credentials/re-platform-workflow-dealer-3d5738fcc1f9.json

Important Notes:

• GCP_PROJECT_ID: Should match the project_id in your credentials JSON file (currently: re-platform-workflow-dealer)
• GCP_BUCKET_NAME: The name of your GCS bucket (create one in GCP Console if needed)
• GCP_KEY_FILE: Path to your service account credentials JSON file (relative to project root or absolute path)

2. Create GCS Bucket (if not exists)

1. Go to Google Cloud Console
2. Navigate to Cloud Storage > Buckets
3. Click Create Bucket
4. Choose a unique bucket name (e.g., re-workflow-documents)
5. Select a location for your bucket
6. Set permissions:
   • Make bucket publicly readable (for public URLs) OR
   • Keep private and use signed URLs (more secure)

3. Grant Service Account Permissions

Your service account (re-bridge-workflow@re-platform-workflow-dealer.iam.gserviceaccount.com) needs:

• Storage Object Admin role (to upload/delete files)
• Storage Object Viewer role (to read files)

4. Verify Configuration

The system will:

• ✅ Automatically detect if GCS is configured
• ✅ Fall back to local storage if GCS is not configured
• ✅ Upload files to GCS when configured
• ✅ Store GCS URLs in the database
• ✅ Redirect downloads/previews to GCS URLs

File Storage Structure

Files are organized in GCS by request number with subfolders for documents and attachments:

reflow-documents-uat/
├── requests/
│   ├── REQ-2025-12-0001/
│   │   ├── documents/
│   │   │   ├── {timestamp}-{hash}-{filename}
│   │   │   └── ...
│   │   └── attachments/
│   │       ├── {timestamp}-{hash}-{filename}
│   │       └── ...
│   ├── REQ-2025-12-0002/
│   │   ├── documents/
│   │   └── attachments/
│   └── ...

• Documents: requests/{requestNumber}/documents/{timestamp}-{hash}-{filename}
• Work Note Attachments: requests/{requestNumber}/attachments/{timestamp}-{hash}-{filename}

This structure makes it easy to:

• Track all files for a specific request
• Organize documents vs attachments separately
• Navigate and manage files in GCS console

How It Works

Upload Flow

1. File is received via multer (memory storage)
2. File buffer is uploaded to GCS
3. GCS returns a public URL
4. URL is stored in database (storage_url field)
5. Local file is deleted (if it existed)

Download/Preview Flow

1. System checks if storage_url is a GCS URL
2. If GCS URL: Redirects to GCS public URL
3. If local path: Serves file from local storage

Troubleshooting

Files not uploading to GCS

• Check .env configuration matches your credentials
• Verify service account has correct permissions
• Check bucket name exists and is accessible
• Review application logs for GCS errors

Files uploading but not accessible

• Verify bucket permissions (public read or signed URLs)
• Check CORS configuration if accessing from browser
• Ensure storage_url is being saved correctly in database

Fallback to Local Storage

If GCS is not configured or fails, the system will:

• Log a warning
• Continue using local file storage
• Store local paths in database

Testing

After configuration:

1. Upload a document via API
2. Check database - storage_url should contain GCS URL
3. Try downloading/previewing the document
4. Verify file is accessible at GCS URL

Security Notes

• Public Buckets: Files are publicly accessible via URL
• Private Buckets: Consider using signed URLs for better security
• Service Account: Keep credentials file secure, never commit to git
• Bucket Policies: Configure bucket-level permissions as needed