xyz-coffee

📂 Project Structure

XYZ-COFFEE/
├── docs/                  # API Documentation and image assets
├── xyz-backend/           # Spring Boot 4 REST API
│   └── xyz-api-collection/# Bruno/Postman collection for API testing
├── xyz-frontend/          # React 19 + Vite Web App
├── docker-compose.yml     # Local services for Redis
└── .env.example           # Environment variables template

🚀 Getting Started

Step 1: Clone the Repository

git clone [https://github.com/MinhKhoixyz/xyz-coffee.git](https://github.com/MinhKhoixyz/xyz-coffee.git)
cd xyz-coffee

Step 2: Start Redis Cache

docker compose up -d

Step 3: Configure Environment Variables

Instead of manual renaming, use the following terminal commands to create your .env file and then fill in your credentials.

1. Create the .env file

Run the command corresponding to your operating system or terminal:

• macOS / Linux / Git Bash:

    cp .env.example .env

• Windows (Command Prompt - CMD):

    copy .env.example .env

• Windows (PowerShell):

    cp .env.example .env

2. Fill in the required API keys

Open the newly created .env file. It will look exactly like the snippet below. Update the placeholder values with your real credentials:

• Supabase: Go to Project Settings > Database > Copy the JDBC Connection String and your password.
• Cloudinary: Log in to your Dashboard > Copy Cloud Name, API Key, and API Secret.
• PayOS: Access your Payment Channel > Copy Client ID, API Key, and Checksum Key.

# ==============================================================================
# 🚀 HOW TO SET UP YOUR ENVIRONMENT
# 1. Rename this file to `.env` (or use the terminal commands above)
# 2. Replace the text below with your real information.
# ==============================================================================

# --- 1. DATABASE SETUP (POSTGRESQL - SUPABASE) ---
# Format: jdbc:postgresql://<host>:<port>/<database_name>
DB_URL=jdbc:postgresql://db.your_project_id.supabase.co:5432/postgres
DB_USERNAME=postgres
DB_PASSWORD=your_supabase_db_password

# --- 2. REDIS CACHE SETUP ---
REDIS_PASSWORD=your_redis_password

# --- 3. SECURITY & LOGIN (JWT) ---
JWT_SECRET=your_generated_jwt_secret_string

# --- 4. CLOUD IMAGE STORAGE (CLOUDINARY) ---
CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# --- 5. PAYOS PAYMENT GATEWAY ---
PAYOS_CLIENT_ID=your_payos_client_id
PAYOS_API_KEY=your_payos_api_key
PAYOS_CHECKSUM_KEY=your_payos_checksum_key

# --- 6. DOCKER HUB DEPLOYMENT ---
DOCKER_USERNAME=your_dockerhub_username

# --- 7. SYSTEM SETUP ---
ROOT_USERNAME=your_root_username
ROOT_EMAIL=your_root_email
ROOT_PASSWORD=your_root_password

Step 4: Run Backend & Auto-Init DB

cd xyz-backend
./mvnw clean spring-boot:run

Step 5: Run Frontend

cd xyz-frontend
npm install
npm run dev:all

Step 6: Log in and Test

Access the web app at: http://localhost:5173

Default Credentials:

• Username: root (or your configured ROOT_USERNAME)
• Password: root123@ (or your configured ROOT_PASSWORD)

Step 7: Set up PayOS Webhook (Local Testing)

To receive payment success callbacks locally, you must expose your backend to the internet using Ngrok.

1. Start Ngrok: Open a new terminal and expose port 8080 (where the backend runs):

   ngrok http 8080

2. Copy the Forwarding URL: Ngrok will give you a public URL (e.g., https://abcd-1234.ngrok-free.app).
3. Configure PayOS Webhook:
   • Go to the PayOS Dashboard.
   • Open your Payment Channel Settings.
   • Paste the Ngrok URL appended with /api/v1/webhook/payos into the Webhook URL field.
   • Example: https://abcd-1234.ngrok-free.app/api/v1/webhook/payos
   • Save changes.

📚 API Documentation

• Full API specifications and authentication flows are detailed in docs/API-DOCS.md.