A modern web application to browse and view images from your Google Cloud Storage buckets. Built with FastAPI backend and Svelte frontend.
- 🗂️ Bucket Selection: Browse and select from all your GCS buckets
- 🖼️ Image Gallery: View all images in a beautiful grid layout
- 🔍 Search & Filter: Filter images by prefix/folder
- 🔐 Secure Access: Generate signed URLs for private bucket access
- ⚡ Fast & Async: Built with async/await for optimal performance
- 🎨 Modern UI: Beautiful gradient design with smooth interactions
- 📱 Responsive: Works great on desktop and mobile devices
┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐
│ Svelte │ │ FastAPI │ │ Google Cloud │
│ Frontend │ ◄─────► │ Backend │ ◄─────► │ Storage │
│ (Port 5173) │ │ (Port 8000) │ │ │
└─────────────────┘ └─────────────────┘ └──────────────────┘
src/api.py: REST API endpoints for buckets and imagessrc/gcs_service.py: Google Cloud Storage service layersrc/config.py: Configuration management with Pydantic- Automatic CORS handling for frontend communication
- Signed URL generation for secure image access
- Component-based architecture with reactive stores
- BucketSelector: Display and select GCS buckets
- ImageGallery: Grid view of all images with search
- ImageModal: Full-size image viewer with metadata
- Axios for API communication
- Python 3.11+ installed
- Node.js 18+ and npm installed
- uv package manager (install guide)
- Google Cloud Project with Storage API enabled
- Service Account JSON with Storage permissions
# The repository is already in your workspace
cd /home/human/REPOS/google_cloud_bucket_viewerPlace your service account JSON file at:
credentials/googlecloud/sa.json
Or update the path in .env
Edit .env file with your configuration:
# Google Cloud Storage Configuration
GCS_PROJECT_ID=your-gcp-project-id
GCS_BUCKET_NAME=your-default-bucket-name # Optional
GOOGLE_APPLICATION_CREDENTIALS=credentials/googlecloud/sa.json# Install Python dependencies with uv
uv sync
# Install Node dependencies
cd frontend && npm install && cd ..Option A: Use the startup script (recommended)
./run.shOption B: Run manually
# Terminal 1: Start backend
uv run python -m src.api
# Terminal 2: Start frontend
cd frontend && npm run dev- Frontend: http://localhost:5173
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
- Select a Bucket: Choose from your available GCS buckets
- Browse Images: View all images in a grid layout
- Filter Images: Use the search bar to filter by prefix/folder
- View Details: Click any image to see full size with metadata
- Download: Download images or open in a new tab
# GCS Settings
GCS_PROJECT_ID=your-project-id
GCS_BUCKET_NAME=your-bucket-name
GOOGLE_APPLICATION_CREDENTIALS=credentials/googlecloud/sa.json
# API Settings
API_HOST=0.0.0.0
API_PORT=8000
API_RELOAD=True
# CORS Settings
CORS_ORIGINS=["http://localhost:5173"]
# Signed URL expiration (minutes)
SIGNED_URL_EXPIRATION_MINUTES=60- JPEG/JPG
- PNG
- GIF
- WebP
- BMP
- Signed URLs: All image access uses time-limited signed URLs
- CORS Protection: Configured CORS prevents unauthorized access
- Service Account: Uses least-privilege service account credentials
- No Public Access: Images don't need to be publicly accessible
google_cloud_bucket_viewer/
├── src/
│ ├── __init__.py
│ ├── api.py # FastAPI application
│ ├── gcs_service.py # GCS service layer
│ ├── config.py # Configuration
│ └── main.py # (legacy)
├── frontend/
│ ├── src/
│ │ ├── components/
│ │ │ ├── BucketSelector.svelte
│ │ │ ├── ImageGallery.svelte
│ │ │ └── ImageModal.svelte
│ │ ├── stores/
│ │ │ └── bucket.js
│ │ ├── lib/
│ │ │ └── api.js
│ │ ├── App.svelte
│ │ └── main.js
│ ├── index.html
│ ├── package.json
│ └── vite.config.js
├── credentials/
│ └── googlecloud/
│ └── sa.json # Your service account key
├── tests/
│ └── test_main.py
├── .env # Environment configuration
├── pyproject.toml # Python dependencies
├── run.sh # Startup script
└── README.md
# Run with auto-reload
uv run python -m src.api
# Run tests
uv run pytest
# Format code
uv run ruff format src/
# Lint code
uv run ruff check src/cd frontend
# Development server with hot reload
npm run dev
# Build for production
npm run build
# Preview production build
npm run preview- Verify your service account JSON is in the correct location
- Check that
GCS_PROJECT_IDis set correctly in.env - Ensure the service account has
Storage AdminorStorage Object Viewerrole
- Verify the bucket contains image files with supported extensions
- Try clearing the prefix filter
- Check bucket permissions
- Ensure the frontend URL is in
CORS_ORIGINSin.env - Restart the backend after changing
.env
The import errors shown are expected before installing dependencies. Run:
uv sync| Method | Endpoint | Description |
|---|---|---|
| GET | / |
Root endpoint with API info |
| GET | /api/health |
Health check |
| GET | /api/buckets |
List all buckets |
| GET | /api/images/{bucket} |
List images in bucket |
| GET | /api/images/{bucket}/{blob} |
Get image with signed URL |
| POST | /api/signed-url/{bucket} |
Generate signed URL |
This project follows the guidelines in .github/copilot-instructions.md:
- Python 3.11+ with type hints
- PEP 8 formatting with
ruff - Async/await for I/O operations
- Comprehensive error handling
- Tests with
pytest
This project is for personal/educational use. Ensure compliance with Google Cloud Platform terms of service.
- Built with FastAPI
- Frontend powered by Svelte
- Google Cloud Storage Python Client
- Package management with uv
Made with ❤️ for viewing GCS bucket images