A full-stack hotel management system built with Spring Boot 3.5 and Java 21, featuring secure authentication, payment processing, and real-time room management.
- Features
- Tech Stack
- Architecture
- Prerequisites
- Quick Start
- Configuration
- API Reference
- Database Migrations
- Project Structure
- Contributing
- Troubleshooting
- License
- Authentication & Authorization - JWT-based authentication with Keycloak integration
- Room Management - CRUD operations for rooms with image upload support
- Reservation System - Complete booking workflow with check-in/check-out
- Payment Processing - Stripe integration for secure payments
- Email Notifications - OTP verification and booking confirmations
- Caching - Redis-based caching for improved performance
- Database Migrations - Flyway for version-controlled schema changes
| Technology | Version | Purpose |
|---|---|---|
| Java | 21 | Programming Language |
| Spring Boot | 3.5.7 | Application Framework |
| Spring Security | - | Authentication & Authorization |
| Spring Data JPA | - | Database ORM |
| Hibernate | - | JPA Implementation |
| Technology | Version | Purpose |
|---|---|---|
| PostgreSQL | 15 | Primary Database |
| Redis | 7 | Caching & Session Storage |
| Flyway | - | Database Migration |
| Technology | Version | Purpose |
|---|---|---|
| Keycloak | 23.0.0 | Identity & Access Management |
| JWT (jjwt) | 0.12.3 | Token-based Authentication |
| Stripe | - | Payment Processing |
| Technology | Purpose |
|---|---|
| Docker & Docker Compose | Containerization |
| Maven | Build Tool |
| Lombok | Boilerplate Reduction |
| Apache Commons Lang3 | Utilities |
┌─────────────────────────────────────────────────────────────┐
│ Clients │
│ (Web Browser / Mobile App) │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Spring Boot API │
│ (Port 8080) │
├─────────────────────────────────────────────────────────────┤
│ Controllers → Services → Repositories → Entities │
└───────┬──────────────┬──────────────┬──────────────────────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌──────────┐ ┌─────────────┐
│ PostgreSQL │ │ Redis │ │ Keycloak │
│ (Port 5432) │ │ (6379) │ │ (Port 8180) │
└───────────────┘ └──────────┘ └─────────────┘
Ensure you have the following installed:
For a streamlined setup experience, use our automated scripts:
Windows:
setup.cmdLinux/macOS:
chmod +x setup.sh
./setup.shThese scripts will:
- Check all prerequisites (Java, Maven, Docker)
- Start Docker services (PostgreSQL, Redis, Keycloak)
- Wait for all services to be healthy
- Build the application
- Optionally start the application
git clone https://github.com/thanhhoa3514/hotel-management-v2.git
cd hotel-management-v2/quanlikhachsan# Start PostgreSQL, Redis, and Keycloak
docker-compose up -d
# Verify all services are healthy
docker-compose psService Health Check:
| Service | URL | Credentials |
|---|---|---|
| PostgreSQL | localhost:5432 |
hoteluser / hotelpass123 |
| Redis | localhost:6379 |
Password: redis123 |
| Keycloak | http://localhost:8180 |
admin / admin123 |
# Clean and build (skip tests for faster build)
mvn clean install -DskipTests
# Run the application
mvn spring-boot:runThe API will be available at: http://localhost:8080
# Test the API
curl http://localhost:8080/api/v1/roomsCreate a .env file or set the following environment variables:
| Variable | Default | Description |
|---|---|---|
SPRING_DATASOURCE_URL |
jdbc:postgresql://localhost:5432/hotelmanagement |
Database URL |
SPRING_DATASOURCE_USERNAME |
hoteluser |
Database username |
SPRING_DATASOURCE_PASSWORD |
hotelpass123 |
Database password |
REDIS_HOST |
localhost |
Redis hostname |
REDIS_PORT |
6379 |
Redis port |
REDIS_PASSWORD |
redis123 |
Redis password |
KEYCLOAK_AUTH_SERVER_URL |
http://localhost:8180 |
Keycloak server URL |
JWT_SECRET |
Auto-generated | JWT signing secret |
JWT_EXPIRATION |
86400000 |
Token expiration (24 hours) |
MAIL_HOST |
smtp.gmail.com |
SMTP server |
MAIL_PORT |
587 |
SMTP port |
MAIL_USERNAME |
- | Email username |
MAIL_PASSWORD |
- | Email password |
STRIPE_SECRET_KEY |
- | Stripe API secret key |
STRIPE_WEBHOOK_SECRET |
- | Stripe webhook secret |
Main configuration file: src/main/resources/application.yml
spring:
datasource:
url: ${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/hotelmanagement}
username: ${SPRING_DATASOURCE_USERNAME:hoteluser}
password: ${SPRING_DATASOURCE_PASSWORD:hotelpass123}
jpa:
hibernate:
ddl-auto: validate # Flyway manages schema
flyway:
enabled: true
baseline-on-migrate: true| Method | Endpoint | Description |
|---|---|---|
POST |
/api/v1/reservations |
Create a reservation |
GET |
/api/v1/reservations/{id} |
Get reservation by ID |
GET |
/api/v1/reservations |
List all reservations |
GET |
/api/v1/reservations/guest/{keycloakUserId} |
Get guest reservations |
PUT |
/api/v1/reservations/{id} |
Update reservation |
POST |
/api/v1/reservations/{id}/check-in |
Check-in |
POST |
/api/v1/reservations/{id}/check-out |
Check-out |
POST |
/api/v1/reservations/{id}/cancel |
Cancel reservation |
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/rooms |
List all rooms |
GET |
/api/v1/rooms/{id} |
Get room by ID |
POST |
/api/v1/rooms/check-availability |
Check room availability |
GET |
/api/v1/rooms/available?checkIn=&checkOut= |
Get available rooms |
This project uses Flyway for database migrations.
src/main/resources/db/migration/
├── V1__Initial_schema.sql
├── V2__Add_capacity_and_size_to_room_types.sql
├── V3__Add_Payment_paymentstatus.sql
└── V4__Add_stripe_session_id_to_payments.sql
-
Create a new file following the naming convention:
V{version}__{description}.sqlExample:
V5__Add_guest_preferences.sql -
Migrations run automatically on application startup
For detailed guidance, see FLYWAY_GUIDE.md
src/main/java/com/hotelmanagement/quanlikhachsan/
├── config/ # Configuration classes
├── controller/ # REST API controllers
├── dto/ # Data Transfer Objects
├── exception/ # Custom exceptions & handlers
├── mapper/ # Entity-DTO mappers
├── model/ # JPA Entities
├── repository/ # Spring Data JPA repositories
├── security/ # Security configuration
├── services/ # Business logic
├── util/ # Utility classes
└── QuanlikhachsanApplication.java
We welcome contributions! Please follow these steps:
git clone https://github.com/YOUR_USERNAME/hotel-management-v2.git
cd hotel-management-v2git checkout -b feature/your-feature-name- Follow existing code style and conventions
- Add/update tests for new functionality
- Update documentation if needed
mvn testgit add .
git commit -m "feat: add your feature description"
git push origin feature/your-feature-nameOpen a PR against the main branch with a clear description of your changes.
Error: Type mismatch between Entity and Database
Solution:
docker-compose down -v
docker-compose up -dError: Keycloak hasn't finished starting
Solution:
# Wait 30-60 seconds and check health
curl http://localhost:8180/health/readySolution:
docker exec -it hotel_redis redis-cli -a redis123 PING
# If not responding, restart Redis
docker-compose restart redisSolution: Reset the database completely:
docker-compose down -v
docker volume rm quanlikhachsan_postgres_data
docker volume rm quanlikhachsan_redis_data
docker-compose up -d- SETUP.md - Detailed setup instructions
- FLYWAY_GUIDE.md - Database migration guide
- KEYCLOAK_MANUAL_SETUP.md - Keycloak configuration
- IMAGE_UPLOAD.md - Image upload functionality
- REDIS_CACHING_PATTERNS.md - Redis caching strategies
- MIGRATION_GUIDE.md - Migration best practices
This project is licensed under the MIT License - see the LICENSE file for details.
For questions or issues, please create an issue on GitHub.
Made with ❤️ by thanhhoa3514