Skip to main content
This guide shows you how to run Iquea Commerce locally, access the application, and troubleshoot common startup issues.

​
Starting the Application

Iquea Commerce consists of two separate servers that must run simultaneously:
  1. Backend API (Spring Boot on port 8080)
  2. Frontend UI (Vite dev server on port 5173)
You’ll need two terminal windows open - one for the backend and one for the frontend.

​
Running the Backend

1

Navigate to Backend Directory

Open a terminal and navigate to the backend folder:
cd Iqüea_back
2

Start the Spring Boot Server

Run the application using Maven Wrapper:
./mvnw spring-boot:run
First startup may take 30-60 seconds as Hibernate creates database tables and loads initial data from data.sql.
3

Verify Backend is Running

Look for this message in the console:
Started IqueaApplication in X.XXX seconds (process running for X.XXX)
The backend API is now accessible at:
http://localhost:8080
Test the API:
curl http://localhost:8080/api/productos
You should receive a JSON response with the list of products.

​
Running the Frontend

1

Open a New Terminal

Keep the backend terminal running and open a second terminal window.
2

Navigate to Frontend Directory

cd Iquea_front
3

Start the Vite Dev Server

npm run dev
You should see output similar to:
VITE v7.3.1  ready in XXX ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help
4

Access the Application

Open your browser and navigate to:
http://localhost:5173
The Iquea Commerce homepage should load with the product catalog.

​
Accessing the Application

​
Application URLs

ServiceURLDescription
Frontend (UI)http://localhost:5173React application (Vite dev server)
Backend (API)http://localhost:8080Spring Boot REST API
API Endpointshttp://localhost:8080/api/*RESTful API resources

​
Test User Accounts

The application comes with pre-configured test accounts loaded from data.sql:

Admin Account

Username: admin
Password: password123
Permissions: Full product and category management

Customer Account 1

Username: maria123
Password: password123
Permissions: Browse products, place orders

Customer Account 2

Username: carlos99
Password: password123
Permissions: Browse products, place orders
Login credentials are case-sensitive. Make sure to use lowercase usernames.

​
Testing the Application

​
1. Browse Products (No Authentication Required)

  • Visit http://localhost:5173
  • Browse the product catalog organized by categories
  • Use the search functionality
  • View product details

​
2. Login as Customer

  1. Click the Login button
  2. Enter credentials:
    • Username: maria123
    • Password: password123
  3. You can now:
    • Add products to cart
    • Place orders
    • View order history

​
3. Login as Admin

  1. Log out if currently logged in
  2. Login with admin credentials:
    • Username: admin
    • Password: password123
  3. You can now:
    • Create new products
    • Edit existing products
    • Delete products
    • Manage categories

​
4. Test API Endpoints

curl http://localhost:8080/api/productos

​
Stopping the Application

​
Stop Backend (Spring Boot)

In the backend terminal, press: 
Ctrl + C
The Spring Boot application will gracefully shut down.

​
Stop Frontend (Vite)

In the frontend terminal, press: 
Ctrl + C
The Vite dev server will stop immediately.

​
Troubleshooting Startup Issues

​
Backend Issues

​
Error: “Port 8080 already in use”

Problem: Another application is using port 8080. Solution 1: Stop the conflicting process: 
# Linux/macOS
lsof -ti:8080 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 8080).OwningProcess | Stop-Process
Solution 2: Change the backend port in application.properties: 
server.port=9090
Don’t forget to update CORS configuration if you change the port.

​
Error: “Access denied for user ‘root’@‘localhost’”

Problem: Database credentials are incorrect or user doesn’t have permissions. Solutions:
  1. Verify MySQL is running: 
    sudo systemctl status mysql  # Linux
net start MySQL80            # Windows
  2. Test database connection: 
    mysql -u root -p
  3. Update credentials using environment variables: 
    export DB_USERNAME="your_username"
export DB_PASSWORD="your_password"
  4. Grant database permissions: 
    GRANT ALL PRIVILEGES ON apiIquea.* TO 'root'@'localhost';
FLUSH PRIVILEGES;

​
Error: “Table ‘apiIquea.producto’ doesn’t exist”

Problem: Database schema wasn’t created automatically. Solutions:
  1. Verify application.properties setting: 
    spring.jpa.hibernate.ddl-auto=update
  2. Check database URL includes createDatabaseIfNotExist: 
    spring.datasource.url=jdbc:mysql://localhost:3306/apiIquea?createDatabaseIfNotExist=true
  3. Manually create database: 
    CREATE DATABASE apiIquea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  4. Restart the backend to trigger schema creation.

​
Error: “Failed to load initial data from data.sql”

Problem: Data initialization script failed, often due to constraint violations or existing data. Solutions:
  1. Drop and recreate database: 
    DROP DATABASE apiIquea;
CREATE DATABASE apiIquea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  2. Temporarily change ddl-auto to create: 
    spring.jpa.hibernate.ddl-auto=create
    ddl-auto=create will drop all tables on startup. Change back to update after successful initialization.

​
Frontend Issues

​
Error: “Port 5173 already in use”

Problem: Another Vite dev server or application is using port 5173. Solution 1: Kill the process: 
# Linux/macOS
lsof -ti:5173 | xargs kill -9

# Windows
netstat -ano | findstr :5173
taskkill /PID <PID> /F
Solution 2: Specify a different port: 
npm run dev -- --port 5174

​
Error: “Failed to fetch” or “Network Error”

Problem: Frontend can’t connect to backend API. Solutions:
  1. Verify backend is running: 
    curl http://localhost:8080/api/productos
  2. Check CORS configuration in SecurityConfig.java: 
    configuration.setAllowedOrigins(Arrays.asList("http://localhost:5173"));
  3. Clear browser cache and cookies (Ctrl+Shift+Delete)
  4. Check browser console for specific error messages (F12)

​
Error: “Module not found” or “Cannot find module”

Problem: Node dependencies are missing or corrupted. Solutions:
  1. Reinstall dependencies: 
    rm -rf node_modules package-lock.json
npm install
  2. Clear npm cache: 
    npm cache clean --force
npm install

​
Authentication Issues

​
Problem: “Invalid credentials” when logging in

Solutions:
  1. Verify initial data was loaded: 
    USE apiIquea;
SELECT * FROM Usuario;
  2. Check passwords are hashed with BCrypt (they should start with $2a$ or $2b$)
  3. Ensure usernames are lowercase
  4. Re-run data.sql manually if users are missing: 
    mysql -u root -p apiIquea < src/main/resources/data.sql

​
Problem: JWT token expires immediately

Solution: Check JwtUtil.java expiration setting: 
private static final long EXPIRATION_MS = 86400000L; // 24 hours in milliseconds
Ensure your system clock is set correctly (JWT uses timestamps).

​
Development Tips

​
Hot Reload

  • Backend: Spring Boot DevTools enables automatic restart on code changes. Just save your Java files and the server will restart.
  • Frontend: Vite provides instant Hot Module Replacement (HMR). Changes to React components appear immediately without full page reload.

​
Viewing Logs

Backend logs: All SQL statements and Spring Boot logs appear in the terminal where you ran mvnw spring-boot:run. Frontend logs: Use browser DevTools (F12) to view console logs, network requests, and errors.

​
Database Inspection

Option 1: MySQL Workbench (GUI) Connect to localhost:3306 and browse the apiIquea database. Option 2: Command Line 
mysql -u root -p
mysql> USE apiIquea;
mysql> SHOW TABLES;
mysql> SELECT * FROM Producto LIMIT 5;

​
Next Steps

Now that your application is running:
For production deployment, refer to the Deployment Guide (coming soon) for instructions on building production bundles and deploying to cloud platforms.

Build docs developers (and LLMs) love

Get started for freeTalk to us