Hexagon Feed System - Project Startup Instructions

Date: October 19, 2025
Status: Ready to Run

✅ Codebase Analysis Complete

A comprehensive codebase analysis has been completed. See Codebase_Analysis_Report.md for the full 1000+ line detailed report.

Quick Summary:

Overall Score: 4.1/5 (82%)
Status: Production-ready with minor enhancements needed
Architecture: ⭐⭐⭐⭐⭐ (5/5)
Code Quality: ⭐⭐⭐⭐☆ (4/5)
Test Coverage: 30 test files across all layers

🚀 How to Run the Project

Prerequisites

Docker Desktop - Must be running
Java 17+ - ✅ Detected: Java 24.0.2
Maven 3.6+ - ✅ Detected: Maven 3.9.11
Port Availability:
- 8080 (Application)
- 5432 (PostgreSQL)
- 6379 (Redis)
- 9092 (Kafka)
- 2181 (Zookeeper)

Step-by-Step Startup Guide

Step 1: Start Docker Services

# Navigate to project root
cd '/Users/mihirjain/Thoughts All stack/Java-Feed-System-Service'

# Start Docker Desktop first (via GUI or command)
# Then start all services
docker-compose up -d

# Verify services are running
docker-compose ps

Expected output:

NAME                    STATUS
hexfeed-postgres        Up
hexfeed-redis           Up
hexfeed-kafka           Up
hexfeed-zookeeper       Up
hexfeed-prometheus      Up
hexfeed-grafana         Up
hexfeed-cassandra       Up (optional)

Step 2: Wait for Services to Initialize

# Check PostgreSQL is ready
docker-compose logs postgres | grep "ready to accept connections"

# Check Kafka is ready
docker-compose logs kafka | grep "started"

# Check Redis is ready
docker-compose logs redis | grep "Ready to accept connections"

Step 3: Run the Application

# Navigate to backend directory
cd hexfeed-backend

# Option A: Run with Maven (Development Mode)
./mvnw spring-boot:run

# Option B: Build and run JAR (Production-like)
./mvnw clean package -DskipTests
java -jar target/FeedSystemDependencies-0.0.1-SNAPSHOT.jar

# Option C: Run with specific profile
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Step 4: Verify Application Started

# Check application health
curl http://localhost:8080/actuator/health

# Expected response:
# {"status":"UP"}

🧪 Testing the Application

1. Health Check

curl http://localhost:8080/actuator/health

2. Register a User

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "Test@123456"
  }'

3. Login

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "Test@123456"
  }'

Save the access_token from response.

4. Create a Post

curl -X POST http://localhost:8080/api/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "content": "Hello from HexFeed!",
    "latitude": 37.7749,
    "longitude": -122.4194
  }'

5. Get Location-Based Feed

curl -X GET "http://localhost:8080/api/v1/feed?latitude=37.7749&longitude=-122.4194&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

🐳 Docker Services Management

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f postgres
docker-compose logs -f redis
docker-compose logs -f kafka
docker-compose logs -f hexfeed-backend

Stop Services

# Stop all
docker-compose down

# Stop and remove volumes (clean slate)
docker-compose down -v

Restart Services

# Restart all
docker-compose restart

# Restart specific service
docker-compose restart postgres

📊 Management UIs

Once Docker services are running, access these UIs:

PgAdmin (PostgreSQL Management)

URL: http://localhost:8083
Email: admin@hexfeed.com
Password: admin123

Redis Commander (Redis Management)

URL: http://localhost:8082
Auto-connects to Redis

Kafka UI (Kafka Management)

URL: http://localhost:8081
View topics, messages, consumer groups

Grafana (Monitoring)

URL: http://localhost:3000
Username: admin
Password: admin123

Prometheus (Metrics)

URL: http://localhost:9090
View metrics and queries

🧪 Running Tests

Run All Tests

cd hexfeed-backend
./mvnw test

Run Specific Test Class

./mvnw test -Dtest=FeedAggregationServiceTest

Run Integration Tests

./mvnw test -Dtest=*IntegrationTest

Skip Tests (During Build)

./mvnw clean package -DskipTests

🔧 Troubleshooting

Issue: Docker Not Running

# Error: Cannot connect to Docker daemon
# Solution: Start Docker Desktop application
open -a Docker

# Wait for Docker to start, then verify
docker ps

Issue: Port Already in Use

# Find process using port 8080
lsof -i :8080

# Kill process
kill -9 <PID>

Issue: Database Connection Failed

# Check PostgreSQL is running
docker-compose ps postgres

# Check logs
docker-compose logs postgres

# Restart PostgreSQL
docker-compose restart postgres

# Verify connection
docker exec -it hexfeed-postgres psql -U hexfeed_user -d hexfeed_db

Issue: Redis Connection Failed

# Check Redis is running
docker-compose ps redis

# Test Redis connection
docker exec -it hexfeed-redis redis-cli ping
# Expected: PONG

# Restart Redis
docker-compose restart redis

Issue: Kafka Not Ready

# Kafka takes 30-60 seconds to start
# Check logs
docker-compose logs kafka

# Wait for this message:
# "Kafka Server started"

# Verify Kafka
docker exec -it hexfeed-kafka kafka-topics --list --bootstrap-server localhost:9092

Issue: Application Fails to Start

# Check application logs
cd hexfeed-backend
cat logs/hexfeed-backend.log

# Common issues:
# 1. Database not ready - wait longer
# 2. Redis not connected - check Redis status
# 3. Port 8080 in use - change port or kill process
# 4. Flyway migration failed - check database schema

Issue: Tests Failing

# TestContainers need Docker
# Ensure Docker Desktop is running

# Run tests with more output
./mvnw test -X

# Skip failing tests temporarily
./mvnw test -Dmaven.test.failure.ignore=true

🌐 API Endpoints Reference

Authentication Endpoints (Public)

Method	Endpoint	Description
POST	/api/v1/auth/register	Register new user
POST	/api/v1/auth/login	Login user
POST	/api/v1/auth/refresh	Refresh access token
GET	/api/v1/auth/verify	Verify token

Feed Endpoints (Protected)

Method	Endpoint	Description
GET	/api/v1/feed	Get location-based feed
GET	/api/v1/feed/health	Health check

Post Endpoints (Protected)

Method	Endpoint	Description
POST	/api/v1/posts	Create new post
GET	/api/v1/posts/user	Get user's posts
GET	/api/v1/posts/{postId}	Get post by ID
DELETE	/api/v1/posts/{postId}	Delete post
GET	/api/v1/posts/health	Health check

WebSocket Endpoint

Protocol	Endpoint	Description
WebSocket	/ws	Real-time feed updates

📝 Configuration Profiles

Development (default)

./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

Detailed logging
H2 in-memory database option
Hot reload enabled

Production

./mvnw spring-boot:run -Dspring-boot.run.profiles=prod

Minimal logging
PostgreSQL required
Optimized for performance

Testing

./mvnw test -Dspring.profiles.active=test

Uses TestContainers
In-memory databases
Fast test execution

📦 Building for Production

Create Executable JAR

cd hexfeed-backend

# Build with tests
./mvnw clean package

# Build without tests (faster)
./mvnw clean package -DskipTests

# JAR location
ls -lh target/FeedSystemDependencies-0.0.1-SNAPSHOT.jar

Run Production JAR

# Set environment variables
export SPRING_PROFILES_ACTIVE=prod
export DATABASE_URL=jdbc:postgresql://localhost:5432/hexfeed_db
export REDIS_HOST=localhost
export KAFKA_BOOTSTRAP_SERVERS=localhost:9092
export JWT_SECRET=your-secure-secret-key-change-in-production

# Run application
java -jar target/FeedSystemDependencies-0.0.1-SNAPSHOT.jar

🔒 Security Configuration

JWT Token Configuration

Edit application.yml:

hexfeed:
  security:
    jwt:
      secret: your-secret-key-change-in-production  # Change this!
      expiration: 86400000  # 24 hours

CORS Configuration

Edit SecurityConfig.java:

configuration.setAllowedOriginPatterns(Arrays.asList(
    "http://localhost:3000",  // React
    "https://yourdomain.com"  // Production
));

📈 Monitoring Setup

Access Prometheus

# Open browser
open http://localhost:9090

# Query examples:
# - jvm_memory_used_bytes
# - http_server_requests_seconds
# - system_cpu_usage

Access Grafana

# Open browser
open http://localhost:3000

# Login: admin / admin123

# Add Prometheus datasource:
# URL: http://prometheus:9090

🎯 Next Steps

Immediate Actions:

✅ Start Docker Desktop
✅ Run docker-compose up -d
✅ Wait 60 seconds for services to initialize
✅ Run ./mvnw spring-boot:run
✅ Test health endpoint
✅ Create test user and post

Short Term (This Week):

Long Term (This Month):

Complete cursor-based pagination
Implement cache stampede prevention
Add health check improvements
Perform security audit
Prepare for Cassandra migration

📚 Additional Resources

Documentation Files:

Codebase_Analysis_Report.md - Comprehensive analysis
API_Testing_Status.md - API testing guide
DeploymentGuide.md - Deployment instructions
ClassArchitectureDiagram.md - Architecture diagrams

Postman Collection:

File: HexFeed_API_Collection.postman_collection.json
Environment: HexFeed_Development_Environment.postman_environment.json
Location: /hexfeed-backend/

Scripts:

test-api.sh - Automated API testing
test-websocket.sh - WebSocket testing
websocket-test-client.html - WebSocket client UI

❓ Questions?

If you encounter any issues:

Check this document's Troubleshooting section
Review application logs: hexfeed-backend/logs/hexfeed-backend.log
Check Docker service logs: docker-compose logs <service-name>
Review Codebase_Analysis_Report.md for architecture details

Status: ✅ Codebase analyzed, documented, and ready to run!
Next Step: Start Docker Desktop and run docker-compose up -d

FilesExpand file tree

Project_Startup_Instructions.md

Latest commit

History