Mini Social Network - Backend API

A production-ready social media backend API built with Spring Boot, featuring user authentication, posts, comments, likes, and follow system with automated CI/CD deployment.

🚀 Live Demo

• API Base URL: https://api.qhieu.dev
• API Documentation: https://api.qhieu.dev/swagger-ui.html

✨ Features

• 🔐 JWT-based authentication with refresh token rotation
• 📧 Email verification for new users
• 👤 User profiles with follow/unfollow system
• 📝 Create, update, delete posts with media upload
• 💬 Nested comments and replies
• ❤️ Like posts and comments
• 📰 Personalized newsfeed
• 🔥 Trending posts algorithm
• 📄 Pagination support
• 📚 OpenAPI/Swagger documentation
• 🐳 Docker containerization
• 🔄 Automated CI/CD pipeline
• 🔒 HTTPS with SSL certificate
• 🌐 Nginx reverse proxy

🛠️ Tech Stack

Backend

• Java 17 - Programming language
• Spring Boot 3.5.5 - Application framework
• Spring Security - Authentication & authorization
• Spring Data JPA - Database ORM
• MySQL 8.0 - Relational database
• JWT (jjwt) - Token-based authentication

Infrastructure

• Docker - Containerization
• Docker Compose - Multi-container orchestration
• Nginx - Reverse proxy & load balancer
• Let's Encrypt - SSL/TLS certificates
• GitHub Actions - CI/CD automation
• DigitalOcean - VPS hosting

Third-party Services

• Cloudinary - Media storage & CDN
• Gmail SMTP - Email delivery

📋 Prerequisites

• JDK 17 or higher
• Maven 3.8+
• MySQL 8.0+
• Docker & Docker Compose (for deployment)
• Cloudinary account
• Gmail account with App Password

🔧 Local Development Setup

1. Clone the repository

git clone https://github.com/ariushieu/mini-social-be.git
cd mini-social-be

2. Configure environment variables

Create .env file in the root directory:

DB_USERNAME=your_db_username
DB_PASSWORD=your_db_password
SECRET_KEY=your_jwt_secret_key_min_256_bits
GMAIL_USERNAME=your_gmail@gmail.com
GMAIL_PASSWORD=your_gmail_app_password
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

3. Create MySQL database

CREATE DATABASE isocial_network CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

4. Run the application

mvn clean install
mvn spring-boot:run

The API will be available at http://localhost:8080

5. Access API Documentation

Open your browser and navigate to:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

🐳 Docker Deployment

Build and run with Docker Compose

docker-compose up -d

Stop containers

docker-compose down

View logs

docker-compose logs -f app

🚀 Production Deployment

The application uses automated CI/CD pipeline with GitHub Actions:

CI Pipeline (All Branches)

• Triggered on every push
• Builds project with Maven
• Runs tests (currently skipped, will be enabled with H2 database)
• Validates code compilation

CD Pipeline (Master Branch Only)

• Builds Docker image
• Pushes to Docker Hub
• SSH to VPS
• Pulls latest image
• Restarts containers
• Cleans up old images

Manual Deployment

# SSH to VPS
ssh user@your-vps-ip

# Navigate to project directory
cd /opt/mini-social-be

# Pull latest changes
docker-compose pull app

# Restart containers
docker-compose up -d app

# Clean up old images
docker image prune -af --filter "until=48h"

📚 API Documentation

Authentication Endpoints

Method	Endpoint	Description	Auth Required
POST	/api/auth/register	Register new user	No
GET	/api/auth/verify?code={code}	Verify email	No
POST	/api/auth/login	Login user	No
POST	/api/auth/refresh	Refresh access token	No

Profile Endpoints

Method	Endpoint	Description	Auth Required
GET	/api/profile/{userId}	Get user profile	Yes

Post Endpoints

Method	Endpoint	Description	Auth Required
POST	/api/posts/create	Create post with media	Yes
PUT	/api/posts/{id}	Update post	Yes
GET	/api/v1/newsfeed	Get personalized newsfeed	Yes
GET	/api/v1/trending	Get trending posts	Yes

Comment Endpoints

Method	Endpoint	Description	Auth Required
POST	/api/v1/posts/{postId}/comments	Create comment/reply	Yes
GET	/api/v1/posts/{postId}/comments	Get post comments	Yes
GET	/api/v1/posts/{postId}/comments/{id}/replies	Get comment replies	Yes
PUT	/api/v1/posts/{postId}/comments/{id}	Update comment	Yes
DELETE	/api/v1/posts/{postId}/comments/{id}	Delete comment	Yes

Like Endpoints

Method	Endpoint	Description	Auth Required
POST	/api/v1/posts/{postId}/likes	Like post	Yes
DELETE	/api/v1/posts/{postId}/likes	Unlike post	Yes
GET	/api/v1/posts/{postId}/likes	Get users who liked	Yes
GET	/api/v1/posts/{postId}/likes/check	Check like status	Yes
POST	/api/v1/comments/{commentId}/likes	Like comment	Yes
DELETE	/api/v1/comments/{commentId}/likes	Unlike comment	Yes

Follow Endpoints

Method	Endpoint	Description	Auth Required
POST	/api/v1/follows/{userId}	Follow user	Yes
DELETE	/api/v1/follows/{userId}	Unfollow user	Yes
GET	/api/v1/follows/{userId}/followers	Get followers (paginated)	Yes
GET	/api/v1/follows/{userId}/following	Get following (paginated)	Yes
GET	/api/v1/follows/{userId}/stats	Get follow statistics	Yes
GET	/api/v1/follows/check/{targetUserId}	Check follow status	Yes

📝 Request Examples

Register User

curl -X POST https://api.qhieu.dev/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "johndoe",
    "email": "john@example.com",
    "password": "Password123",
    "fullName": "John Doe",
    "bio": "Hello world"
  }'

Login

curl -X POST https://api.qhieu.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "password": "Password123"
  }'

Create Post with Media

curl -X POST https://api.qhieu.dev/api/posts/create \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "content=Hello world!" \
  -F "mediaFiles=@image1.jpg" \
  -F "mediaFiles=@image2.png"

Create Comment

curl -X POST https://api.qhieu.dev/api/v1/posts/1/comments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "commentText": "Nice post!",
    "parentCommentId": null
  }'

Follow User

curl -X POST https://api.qhieu.dev/api/v1/follows/2 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

🔐 Authentication

All protected endpoints require JWT access token in the Authorization header:

Authorization: Bearer <access_token>

Token Lifecycle

• Access Token: Valid for 30 minutes
• Refresh Token: Valid for 7 days
• Refresh tokens are rotated on each use for enhanced security

🏗️ Architecture

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Client    │─────▶│    Nginx    │─────▶│  Spring     │
│  (Browser)  │      │   (HTTPS)   │      │  Boot App   │
└─────────────┘      └─────────────┘      └──────┬──────┘
                                                  │
                     ┌────────────────────────────┼────────────────┐
                     │                            │                │
                ┌────▼────┐              ┌────────▼──────┐  ┌──────▼──────┐
                │  MySQL  │              │  Cloudinary   │  │    Gmail    │
                │Database │              │  (Media CDN)  │  │    SMTP     │
                └─────────┘              └───────────────┘  └─────────────┘

📊 Database Schema

Core Tables

• users - User accounts and profiles
• posts - User posts
• post_media - Post media files
• comments - Post comments and replies
• likes - Post and comment likes
• follows - User follow relationships
• notifications - User notifications (future feature)

🔒 Security Features

• Password hashing with BCrypt
• JWT token-based authentication
• Refresh token rotation
• HTTPS/TLS encryption
• CORS configuration
• SQL injection prevention (JPA)
• XSS protection headers
• Rate limiting (Nginx)

🚦 CI/CD Pipeline

GitHub Actions Workflows

CI Workflow (.github/workflows/ci.yml)

• Runs on all branches
• Maven build and package
• Test execution (currently skipped)

CD Workflow (.github/workflows/cd.yml)

• Runs on master branch only
• Docker image build and push
• Automated VPS deployment
• Old image cleanup

Required GitHub Secrets

DOCKER_USERNAME       - Docker Hub username
DOCKER_PASSWORD       - Docker Hub password
VPS_HOST             - VPS IP address
VPS_USERNAME         - VPS SSH username
VPS_SSH_KEY          - VPS SSH private key

📈 Performance Optimizations

• Docker multi-stage builds (reduced image size)
• Nginx reverse proxy with caching
• Database connection pooling (HikariCP)
• JPA query optimization
• Pagination for large datasets
• CDN for media files (Cloudinary)
• Docker log rotation (max 30MB per service)
• Resource limits (MySQL: 512MB, App: 1GB)

🐛 Known Issues & Future Improvements

Current Limitations

• Email verification fails on VPS (SMTP ports blocked by DigitalOcean)
  • Temporary fix: Auto-enable users when email fails
  • Future: Migrate to SendGrid/Mailgun
• Tests are skipped in CI (no H2 database configured)
  • Future: Add H2 for integration tests

Planned Features

• Real-time notifications with WebSocket
• Search functionality
• User mentions and hashtags
• Direct messaging
• Story feature
• Admin dashboard
• Rate limiting per user
• Redis caching layer

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'feat: add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Commit Convention

Follow Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• refactor: - Code refactoring
• test: - Test additions/changes
• chore: - Build/config changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Hieu Nguyen

• GitHub: @ariushieu
• Email: hieunguyen2005q@gmail.com

🙏 Acknowledgments

• Spring Boot team for the excellent framework
• Let's Encrypt for free SSL certificates
• Cloudinary for media storage
• DigitalOcean for VPS hosting

---

Built with ❤️ using Spring Boot