Social Commerce Service ‐ Runbook Overview - Wiz-DevTech/prettygirllz GitHub Wiki

Social Commerce Service - Runbook

Overview

The Social Commerce Service is a Spring Boot application that provides a platform for social commerce interactions, including chat messaging, feed management, and content moderation.

Prerequisites

  • Java 11 or higher
  • PostgreSQL 12+
  • Apache Kafka 2.8+
  • Redis (optional, for caching)

Configuration

Environment Variables

# Database
DB_SECRET=your_database_password

# JWT Security
JWT_SECRET=your_jwt_secret_key
JWT_EXPIRATION_MS=86400000

# Kafka (if external)
KAFKA_BOOTSTRAP_SERVERS=localhost:9092

# Logging Level (optional)
LOGGING_LEVEL_ROOT=INFO

Database Setup

  1. Create PostgreSQL database:
CREATE DATABASE social_commerce_db;
CREATE USER socialcom WITH PASSWORD 'secret';
GRANT ALL PRIVILEGES ON DATABASE social_commerce_db TO socialcom;
  1. Database migration is handled by Flyway automatically on startup
    • Schema: V1__init_schema.sql
    • Seed data: V2__seed_data.sql

Starting the Application

Development Mode

./mvnw spring-boot:run

Production Mode

java -jar social-commerce-service.jar

Docker (if containerized)

docker run -p 8080:8080 \
  -e DB_SECRET=your_password \
  -e JWT_SECRET=your_jwt_secret \
  social-commerce-service:latest

Health Checks

Application Health

  • URL: http://localhost:8080/actuator/health
  • Expected Response: {"status":"UP"}

Database Connection

  • The health endpoint includes database connectivity status
  • If database is down, health status will be DOWN

Available Actuator Endpoints

  • /actuator/health - Application health status
  • /actuator/info - Application information
  • /actuator/metrics - Application metrics
  • /actuator/prometheus - Prometheus metrics (if enabled)

Monitoring

Metrics Collection

  • Application uses Spring Boot Actuator with Prometheus metrics
  • Key metrics to monitor:
    • JVM memory usage
    • HTTP request duration
    • Database connection pool metrics
    • Kafka consumer lag

Logging

  • Default log level: INFO for org.springframework, DEBUG for com.socialcommerce
  • SQL logging is enabled in DEBUG mode
  • Log pattern includes timestamp, thread, level, and message
  • Logs are output to console and file (configurable)

Troubleshooting

Common Issues

Database Connection Issues

  • Symptom: Application fails to start with connection errors
  • Solution:
    • Verify PostgreSQL is running
    • Check database credentials
    • Ensure database exists

JWT Token Issues

  • Symptom: Authentication failures
  • Solution:
    • Verify JWT_SECRET environment variable
    • Check token expiration time
    • Ensure frontend is sending token in Authorization header

Kafka Connection Issues

  • Symptom: Message processing failures
  • Solution:
    • Verify Kafka broker is running on configured port
    • Check consumer group configuration
    • Review Kafka logs for errors

Performance Issues

  • Monitor HikariCP connection pool metrics
  • Check for slow SQL queries in logs
  • Monitor Caffeine cache hit rates
  • Review garbage collection metrics

Backup and Recovery

Database Backup

pg_dump -h localhost -U socialcom social_commerce_db > backup_$(date +%Y%m%d_%H%M%S).sql

Database Restore

psql -h localhost -U socialcom social_commerce_db < backup_file.sql

Security Considerations

JWT Security

  • JWT secret should be strong and environment-specific
  • Tokens expire after 24 hours by default
  • Consider implementing refresh token mechanism

CORS Configuration

  • Currently not explicitly configured in application.yml
  • May need to be added for frontend integration

File Upload Security

  • Max file size: 10MB
  • Max request size: 10MB
  • Ensure uploaded files are validated and scanned

Scaling Considerations

Database Scaling

  • Connection pool configured for 20 max connections
  • Consider read replicas for read-heavy operations
  • Monitor connection pool utilization

Application Scaling

  • Stateless design allows horizontal scaling
  • Consider load balancer configuration
  • Monitor memory usage (Caffeine cache)

Kafka Scaling

  • Consumer group allows multiple instances
  • Monitor consumer lag
  • Consider partition strategy for better distribution

Maintenance Tasks

Regular Tasks

  • Monitor disk usage
  • Review application logs
  • Check for security updates
  • Monitor database performance

Periodic Tasks

  • Database maintenance (VACUUM, ANALYZE)
  • Log rotation and cleanup
  • Metrics cleanup
  • Backup verification

Emergency Procedures

Application Crash

  1. Check logs for error messages
  2. Verify database connectivity
  3. Check system resources (CPU, memory, disk)
  4. Restart application if necessary

Database Issues

  1. Monitor connection counts
  2. Check for long-running queries
  3. Review database logs
  4. Consider connection pool adjustment

High Load Situations

  1. Monitor CPU and memory usage
  2. Check database connection pool utilization
  3. Consider scaling instances
  4. Review slow query log