187 lines
5.0 KiB
Markdown
187 lines
5.0 KiB
Markdown
# SEREACT - Secure Image Management API
|
|
|
|
SEREACT is a secure API for storing, organizing, and retrieving images with advanced search capabilities.
|
|
|
|
## Features
|
|
|
|
- Secure image storage in Google Cloud Storage
|
|
- Team-based organization and access control
|
|
- API key authentication
|
|
- Semantic search using image embeddings
|
|
- Metadata extraction and storage
|
|
- Image processing capabilities
|
|
- Multi-team support
|
|
|
|
## Architecture
|
|
|
|
```
|
|
sereact/
|
|
├── images/ # Sample images for testing
|
|
├── sereact/ # Main application code
|
|
│ ├── deployment/ # Deployment configurations
|
|
│ │ └── cloud-run/ # Google Cloud Run configuration
|
|
│ ├── docs/ # Documentation
|
|
│ │ └── api/ # API documentation
|
|
│ ├── scripts/ # Utility scripts
|
|
│ ├── src/ # Source code
|
|
│ │ ├── api/ # API endpoints
|
|
│ │ │ └── v1/ # API version 1
|
|
│ │ ├── core/ # Core modules
|
|
│ │ ├── db/ # Database models and repositories
|
|
│ │ │ ├── models/ # Data models
|
|
│ │ │ └── repositories/ # Database operations
|
|
│ │ ├── schemas/ # API schemas (request/response)
|
|
│ │ └── services/ # Business logic services
|
|
│ └── tests/ # Test code
|
|
│ ├── api/ # API tests
|
|
│ ├── db/ # Database tests
|
|
│ └── services/ # Service tests
|
|
├── main.py # Application entry point
|
|
├── requirements.txt # Python dependencies
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Technology Stack
|
|
|
|
- FastAPI - Web framework
|
|
- Firestore - Database
|
|
- Google Cloud Storage - Image storage
|
|
- Pinecone - Vector database for semantic search
|
|
- CLIP - Image embedding model
|
|
- NumPy - Scientific computing
|
|
- Pydantic - Data validation
|
|
|
|
## Setup and Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.8+
|
|
- Google Cloud account with Firestore and Storage enabled
|
|
- (Optional) Pinecone account for semantic search
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone https://github.com/yourusername/sereact.git
|
|
cd sereact
|
|
```
|
|
|
|
2. Create and activate a virtual environment:
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # Linux/macOS
|
|
venv\Scripts\activate # Windows
|
|
```
|
|
|
|
3. Install dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
4. Create a `.env` file with the following environment variables:
|
|
```
|
|
# Firestore
|
|
DATABASE_NAME=imagedb
|
|
FIRESTORE_PROJECT_ID=your-gcp-project-id
|
|
FIRESTORE_CREDENTIALS_FILE=path/to/firestore-credentials.json
|
|
|
|
# Google Cloud Storage
|
|
GCS_BUCKET_NAME=your-bucket-name
|
|
GCS_CREDENTIALS_FILE=path/to/credentials.json
|
|
|
|
# Security
|
|
API_KEY_SECRET=your-secret-key
|
|
|
|
# Vector database (optional)
|
|
VECTOR_DB_API_KEY=your-pinecone-api-key
|
|
VECTOR_DB_ENVIRONMENT=your-pinecone-environment
|
|
VECTOR_DB_INDEX_NAME=image-embeddings
|
|
```
|
|
|
|
5. Run the application:
|
|
```bash
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
6. Visit `http://localhost:8000/docs` in your browser to access the API documentation.
|
|
|
|
## API Endpoints
|
|
|
|
The API provides the following main endpoints:
|
|
|
|
- `/api/v1/auth/*` - Authentication and API key management
|
|
- `/api/v1/teams/*` - Team management
|
|
- `/api/v1/users/*` - User management
|
|
- `/api/v1/images/*` - Image upload, download, and management
|
|
- `/api/v1/search/*` - Image search functionality
|
|
|
|
Refer to the Swagger UI documentation at `/docs` for detailed endpoint information.
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
pytest
|
|
```
|
|
|
|
### Creating a New API Version
|
|
|
|
1. Create a new package under `src/api/` (e.g., `v2`)
|
|
2. Implement new endpoints
|
|
3. Update the main.py file to include the new routers
|
|
|
|
## Deployment
|
|
|
|
### Google Cloud Run
|
|
|
|
1. Build the Docker image:
|
|
```bash
|
|
docker build -t gcr.io/your-project/sereact .
|
|
```
|
|
|
|
2. Push to Google Container Registry:
|
|
```bash
|
|
docker push gcr.io/your-project/sereact
|
|
```
|
|
|
|
3. Deploy to Cloud Run:
|
|
```bash
|
|
gcloud run deploy sereact --image gcr.io/your-project/sereact --platform managed
|
|
```
|
|
|
|
## Local Development with Docker Compose
|
|
|
|
To run the application locally using Docker Compose:
|
|
|
|
1. Make sure you have Docker and Docker Compose installed
|
|
2. Run the following command in the project root:
|
|
|
|
```bash
|
|
docker compose up
|
|
```
|
|
|
|
This will:
|
|
- Build the API container based on the Dockerfile
|
|
- Mount your local codebase into the container for live reloading
|
|
- Mount your Firestore credentials for authentication
|
|
- Expose the API on http://localhost:8000
|
|
|
|
To stop the containers:
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
To rebuild containers after making changes to the Dockerfile or requirements:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
## Additional Information
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the LICENSE file for details. |