Skip to content

README.md

Latest commit

 

History

History
188 lines (134 loc) · 6.04 KB

README.md

File metadata and controls

188 lines (134 loc) · 6.04 KB
Raw

Elastic Search Service (ESS)

Back to Microservices

ess is a multi-module Elasticsearch-backed service built around two main use cases:

  • content search across several dataset indexes
  • Reddit-style post submission, voting, and ranked feeds

The runtime lives in ess-app, shared models live in ess-api, and higher-level integration coverage lives in ess-testing.

Stack: Spring Boot, Elasticsearch, Kibana, Spring Security, Swagger/OpenAPI, Cucumber

Docs: ARCHITECTURE.md · ess-api · ess-app · ess-testing

Contents

  1. Quick Start
  2. Module Map
  3. API Surface
  4. Local Runtime
  5. Scheduler and Error Handling
  6. Tests

1. Quick Start

Back to top

Prerequisites:

  • Docker
  • JDK + Maven

Start Elasticsearch and Kibana

docker compose -f microservices/ess/compose.yaml up -d

By default the local stack exposes:

URL Description
http://localhost:9200 Elasticsearch
http://localhost:5601 Kibana

Start the application

mvn -pl microservices/ess/ess-app spring-boot:run

Application URLs:

URL Description
http://localhost:8001/swagger-ui/index.html Swagger UI
http://localhost:8001/v3/api-docs OpenAPI JSON

Create the required indexes

Before using the APIs, create the indexes you need through the admin endpoints:

  • PUT /api/admin/indexes/posts
  • PUT /api/admin/indexes/user-votes
  • PUT /api/admin/indexes/books
  • PUT /api/admin/indexes/companies
  • PUT /api/admin/indexes/movies
  • PUT /api/admin/indexes/music
  • PUT /api/admin/indexes/people

Practical bootstrap order:

  • for search demos: create the content indexes you plan to query
  • for post/vote/ranking demos: create posts and user-votes

Full endpoint details and payload examples live in ess-app → API Reference.

2. Module Map

Back to top

Module Responsibility
ess-api Shared DTOs, enums, validation annotations, API constants
ess-app Spring Boot runtime: controllers, services, Elasticsearch client config, scheduler
ess-testing Cucumber integration tests, downloader utilities, dataset-oriented test support

3. API Surface

Back to top

Area Base path What it does
Admin /api/admin Creates Elasticsearch indexes for content, posts, and user votes
Search /api/services/search Generic wildcard fan-out search plus dedicated wildcard, fuzzy, interval, and span endpoints
Votes /api/services/user-votes Accepts UPVOTE, DOWNVOTE, and NOVOTE, stores one vote doc per (userId, postId)
Posts /api/services/posts Creates new post documents with generated IDs and initial ranking fields
Post ranking /api/services/posts/ranking Reads ranked feeds: best, new, hot, rising, top, and top/{window}

Search notes:

  • SearchService.search() uses Elasticsearch msearch and fans out wildcard queries across metadata-defined fields
  • queryable fields are driven by ess-app/src/main/resources/metadata.json
  • dedicated search endpoints use explicit query factories for wildcard, fuzzy, interval, and span queries

Ranking notes:

  • top sorts by denormalized karma
  • best uses the Wilson score lower bound
  • hot uses a Reddit-style time-decayed score
  • rising emphasizes recent vote velocity
  • top/{window} supports day, week, month, and year

4. Local Runtime

Back to top

The repo-local Docker stack is defined in compose.yaml.

Default local behavior:

  • Elasticsearch image: docker.elastic.co/elasticsearch/elasticsearch:9.3.1-arm64
  • Kibana image: docker.elastic.co/kibana/kibana:9.3.1-arm64
  • Elasticsearch security: enabled
  • Elasticsearch HTTP SSL: disabled
  • default Elasticsearch credentials:
    • user: elastic
    • password: FverGoe0
  • default Kibana system password: JgI820Ee

Important application defaults from ess-app/src/main/resources/application.yaml:

  • app port: 8001
  • Elasticsearch host: localhost:9200
  • SSL to Elasticsearch: disabled by default
  • client timeouts and retry/backoff are configured in the custom Elasticsearch transport
  • scheduler is enabled by default

To stop the local stack:

docker compose -f microservices/ess/compose.yaml down

If you need different local ports, passwords, or image tags, override the compose environment variables such as:

  • ES_LOCAL_VERSION
  • ES_LOCAL_PORT
  • KIBANA_LOCAL_PORT
  • ES_LOCAL_PASSWORD
  • KIBANA_LOCAL_PASSWORD

5. Scheduler and Error Handling

Back to top

Scheduler behavior:

  • SchedulerJobs runs hourly with cron 0 0 * * * *
  • the job is enabled when scheduler.enabled=true
  • it removes user-votes documents older than 365 days

Error handling behavior:

  • validation and malformed-request errors return 400
  • IOException returns 503
  • all other unhandled errors return 500

Security note:

  • the app currently allows anonymous access to all endpoints
  • CSRF is disabled
  • HTTP basic support is configured, but no route currently requires authentication

6. Tests

Back to top

# shared API models and validation
mvn -pl microservices/ess/ess-api test

# Spring Boot application tests
mvn -pl microservices/ess/ess-app test

# Cucumber + Testcontainers integration tests
mvn -pl microservices/ess/ess-testing test

See module-specific docs for more detail: