126 lines
4.1 KiB
Markdown
126 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```env
|
|
# 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](https://console.cloud.google.com/)
|
|
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
|
|
|