upload-source.mp4

upload-more-sources.mp4

matching.mp4

. Quickstart

· Report Bug · Request Feature

Table of Contents

1. About
   • Microservices
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. CI/CD
5. Monitoring
6. Roadmap
7. Contributing
8. License
9. Contact

About The Project

A video recognition system that works like Shazam — but for video. It analyzes short snippets (2–5 seconds), breaks them into keyframes, and uses perceptual hashing to identify the exact or near-exact source, even if the clip has been edited or altered. This preserves the full context of the snippet and enables reliable tracking of original video content.

Key features:

• Upload full video snippets, not just images — automatic extraction of keyframes for context-aware matching.
• Accurate source identification via perceptual hashing tolerant to modifications.
• Optimized for quick, precise matching of short video fragments.
• Scalable microservices architecture built to handle heavy traffic without performance loss.

(back to top)

Microservices

Turron is structured into 6 microservices, each with bounded responsibilities:

• Eureka Server: Manages service discovery using Netflix Eureka with @DiscoveryClient.

• Upload Service: Accepts short videos via REST API, stores them in MinIO, and sends processing tasks to Kafka.

• Frame Extraction Service: Extracts 5-10 keyframes from videos using FFmpeg, normalizes orientation for robustness, and forwards frames to Kafka for hashing.

...

• Hashing Service: Computes pHashes for keyframes and stores it in database.

...

• Search Service: Matches snippet videos to source videos using perceptual hash comparisons with sliding-window Hamming distance, storing results in database.

• API Gateway: Centralized REST API endpoint managing requests, authentication, and response aggregation.

(back to top)

Built With

• 
• 

(back to top)

Quickstart

1. Clone the repository:

   git clone https://github.com/fl1s/turron.git

2. Navigate to the project directory:

   cd turron

3. Create .env.dev file from the .env.example:

   cd .config/secrets

   bash / zsh / powerShell

   cp .env.example .env.dev

   cmd

   copy .env.example .env.dev

4. Start the dev environment with Docker Compose:

   docker-compose --env-file .config/secrets/.env.dev up

5. Verify services are running:

   docker ps

6. Go to the API Endpoints

Getting Started (advanced)

Set up Turron locally using Docker Compose for the dev environment or deploy to Kubernetes for production.

Prerequisites

Ensure you have the following installed:

• Java 21
• Gradle
• Docker and Docker Compose
• kubectl (for prod environment)
• PostgreSQL, Kafka, MinIO (or use Docker Compose)

  java --version
  gradle --version
  docker --version

Installation

1. Clone the repository:

   git clone https://github.com/fl1s/turron.git

2. Navigate to the project directory:

   cd turron

3. Build all microservices with Gradle:

   cd microservice-name
   ./gradlew clean build

4. Start the dev environment with Docker Compose:

   docker-compose up -d

5. Verify services are running:

   docker ps

(back to top)

API Endpoints

Upload snippet-video

POST {{api-gateway}}/api/v1/upload/snippet

Form Data:

Field	Description	Type
file	MP4 video file	file (mp4)

Response:

{
  "snippetId": "..."
}

---

Upload source-video

POST {{api-gateway}}/api/v1/upload/source

Form Data:

Field	Description	Type
file	MP4 video file	file (mp4)

Response:

{
  "sourceId": "..."
}

---

Find best-match

GET {{api-gateway}}/api/v1/search/best-match/:snippetId

Path Parameter:

Parameter	Description	Type
snippetId	Snippet video ID	string

Response:

{
  "downloadUrl": "..."
}

CI/CD

This project uses GitHub Actions.

The .github/workflows/build.yml workflow runs on every push and pull request to the main branch. It performs the following steps:

1. Checks out the repository
2. Sets up Java 21 using the Temurin distribution
3. Caches Gradle dependencies to speed up builds
4. Builds each service defined in the job matrix:
   • eureka-server
   • upload-service
   • extraction-service
   • hashing-service
   • search-service
   • api-gateway
5. Authenticates to GitHub Container Registry (GHCR)
6. Builds and pushes Docker images using a composite action located at .github/actions/docker-build-push

Each Docker image is tagged with:

• latest
• a short Git commit SHA
• a date-based tag in YYYYMMDD format

Monitoring

Our project includes out-of-the-box monitoring setup using Prometheus and Grafana.

How it works

• Each microservice exposes metrics via Spring Boot Actuator on the /actuator/prometheus endpoint.
• Prometheus scrapes these endpoints regularly to collect metrics.
• Grafana connects to Prometheus as a data source to visualize metrics on dashboards.

Prometheus configuration

Prometheus config is located at:
monitoring/prometheus/prometheus.yml

Folder structure

• monitoring/prometheus/ — Prometheus config files
• monitoring/grafana/ — Grafana dashboards and config files

Getting started

1. Start Prometheus using the config from monitoring/prometheus/prometheus.yml(it's already configured in docker-compose).
2. Start Grafana and add Prometheus as a data source (http://localhost:9090).
3. Create your dashboards in Grafana or import community dashboards for Spring Boot metrics.
4. Access your dashboards to monitor service health, performance, and custom metrics.

Cloudflare (optional)

1. In Zero Trust you need to go to Network -> Tunnels, then create a new tunnel with the name of your domain.
2. Get the token and put its value in the field CLOUDFLARED_TUNNEL_TOKEN in .config/secrets/.env.prod.
3. In published application routes, set root route to nginx:80.
4. Also, don't forget to set the minio subdomain (s3.yourdomain) and route to nginx:80.
5. In Additional application settings -> HTTP settings set HTTP Host header value minio:9000
6. In .config/nginx/nginx.conf change server_name to your domain and subdomain.

Contributing

Contributions are welcome to enhance Turron! Follow these steps:

1. Fork the Project.
2. Create your Feature Branch:

   git checkout -b feature/fuzz-buzz-creature

3. Commit your Changes:

   git commit -m 'feat: add some fuzzBuzzCreatureFeature'

4. Push to the Branch:

   git push --set-upstream origin feature/fuzz-buzz-creature

5. Open a Pull Request.

Read our Contributing Guidelines for more details(I also do it later).

Top Contributors

(back to top)

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

(back to top)

Contact

fl1s - GitHub

Project Link: https://github.com/fl1s/turron

(back to top)