Running BodegaX Locally: Frontend and Backend Setup

This page walks you through every step needed to get BodegaX running on your local machine — from cloning the repository to seeing the dashboard load in your browser. The frontend (Angular 17) and the backend (Spring Boot) are maintained in separate repositories and must each be started independently. The Angular dev server runs on port 4200, and the Spring Boot API server runs on port 8080. Both must be running simultaneously for the application to function.

All Angular component files in the BodegaX source code call the backend using hardcoded URLs such as http://localhost:8080/admin/all, http://localhost:8080/productos/all, http://localhost:8080/ventas/create, and so on. The affected files include login.component.ts, register.component.ts, home.component.ts, management.component.ts, history.component.ts, settings.component.ts, despachar-caja.ts, user-form-message.ts, terminar-jornada.ts, and recibir-caja.ts. There are no Angular environment files (environment.ts / environment.prod.ts) in the current codebase. This means that for any production or cloud deployment, you must update every hardcoded URL in the component files or introduce Angular environment files yourself. Do not forget this step before building for production.

Clone the Frontend Repository

Clone the BodegaX Angular frontend from GitHub and navigate into the project root:

git clone https://github.com/Edwin950821/BodegaX.git
cd BodegaX

The repository root contains package.json, angular.json, tsconfig.json, and the src/ directory. The Angular project name inside angular.json is BodegaX-angular, and the build output path is dist/bodega-x-angular/.

Install Node.js Dependencies

Install all frontend dependencies declared in package.json:

npm install

This command downloads and installs every package listed under dependencies and devDependencies, including Angular 17 (@angular/core ^17.0.0), Angular Material (@angular/material ^17.3.8 and @angular/cdk ^17.3.8), RxJS (~7.8.0), jsPDF (^2.5.2), jspdf-autotable (^3.8.4), zone.js (~0.14.2), and all CLI tooling. The node_modules/ directory will be created in the project root.

The project ships with a .vscode/tasks.json that pre-configures an npm: start task (which runs ng serve) and an npm: test task. If you use Visual Studio Code, you can start the development server directly from the Terminal → Run Task menu without typing any commands.

Verify the Angular CLI is available after install:

npx ng version

You should see Angular CLI version 17.x alongside Node.js and TypeScript ~5.2.2 listed in the output.

Set Up the Spring Boot Backend

The Spring Boot backend lives in a separate repository from the Angular frontend. Clone it and configure the database connection before proceeding.Configure src/main/resources/application.properties (or application.yml) in the backend project with your PostgreSQL credentials:

# PostgreSQL data source
spring.datasource.url=jdbc:postgresql://localhost:5432/bodegax
spring.datasource.username=your_db_username
spring.datasource.password=your_db_password

# Hibernate schema management (use 'create' for first run, then switch to 'update')
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# Embedded Tomcat port
server.port=8080

Replace bodegax, your_db_username, and your_db_password with your actual PostgreSQL database name and credentials. The backend listens on port 8080 by default; the Angular source code has this port hardcoded in every HTTP call.

Initialize the PostgreSQL Database

Create an empty database for BodegaX before starting the backend for the first time:

-- Run this in psql or a database client such as pgAdmin or DBeaver
CREATE DATABASE bodegax;

Hibernate Auto-Create (Recommended for Dev)
Manual Migration Scripts

Set spring.jpa.hibernate.ddl-auto=create in application.properties for the very first run. Hibernate will inspect all @Entity classes and generate the schema automatically. After the first successful start, change this value to update to prevent the schema from being dropped and recreated on every restart.

# First run only — creates all tables from JPA entities
spring.jpa.hibernate.ddl-auto=create

If the backend repository includes SQL migration scripts (e.g., in a db/migrations/ directory or managed by Flyway/Liquibase), apply them manually:

psql -U your_db_username -d bodegax -f path/to/migration.sql

Set spring.jpa.hibernate.ddl-auto=validate after applying scripts so Hibernate confirms the schema matches the entities without making changes.

Start the Spring Boot Backend

From the backend project root, start the Spring Boot application using Maven:

mvn spring-boot:run

Spring Boot will start the embedded Tomcat server. Watch the console for a line similar to:

Started BodegaXApplication in 4.321 seconds (JVM running for 4.8)

The REST API is now available at http://localhost:8080. You can confirm it is running by sending a test request:

curl http://localhost:8080/productos/all

If Maven is not on your PATH, you can use the Maven wrapper included in most Spring Boot projects: ./mvnw spring-boot:run (Linux/macOS) or mvnw.cmd spring-boot:run (Windows).

Start the Angular Development Server

With the backend running, start the Angular frontend from the BodegaX/ project root:

ng serve

The Angular CLI compiles the application in development mode (optimization: false, sourceMap: true as configured in angular.json) and starts a local dev server. When you see:

✔ Compiled successfully.

Open your browser and navigate to:

http://localhost:4200

The app will automatically reload whenever you save changes to any source file under src/. There is no need to restart the server during active development.

Building for production instead

To generate an optimized production build rather than running the dev server:

ng build

The Angular CLI runs with the production configuration by default (as set by "defaultConfiguration": "production" in angular.json). This enables:

Full bundle optimization and tree-shaking
Output hashing for cache-busting (outputHashing: all)
Bundle budget enforcement (warning at 500 KB, error at 1 MB for initial bundle)

Build artifacts are placed in dist/bodega-x-angular/. This directory contains the static files (index.html, hashed JS/CSS bundles, favicon.ico, and assets/) that you serve in production.

# Watch mode for development builds (no production optimizations)
npm run watch
# Equivalent to: ng build --watch --configuration development

Create the First Admin User

BodegaX uses role-based access control with two roles: admin and client. The database starts empty, so you must create the first administrator account before logging in through the UI.The registration endpoint is POST http://localhost:8080/admin/create. Use Postman, curl, or any REST client to send the following request:

curl -X POST http://localhost:8080/admin/create \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Admin",
    "correo": "admin@bodegax.com",
    "contrasena": "yourpassword",
    "role": "admin"
  }'

After the user is created, you can log in through the UI at http://localhost:4200. The login component sends credentials to POST http://localhost:8080/admin/login, receives back the user object (including role), and stores the session in sessionStorage under the key bodegax.

Alternatively: seed the database directly

You can insert an admin user directly into PostgreSQL if the REST endpoint is not yet reachable:

-- Passwords in BodegaX are handled by the backend; insert a hashed value
-- or use the application's registration flow instead of raw SQL
INSERT INTO admin (nombre, correo, contrasena, role)
VALUES ('Admin', 'admin@bodegax.com', 'hashed_password_here', 'admin');

Check the backend entity and service classes to confirm the exact column names and whether passwords are stored as bcrypt hashes before inserting directly.

Running Tests

BodegaX includes a Karma + Jasmine unit test suite for the Angular frontend. Tests run in a headless Chrome instance using karma-chrome-launcher.

# Run the full test suite once
ng test

# Or use the npm alias from package.json
npm test

The test configuration uses tsconfig.spec.json and loads zone.js/testing as an additional polyfill. Test results are printed to the terminal and also available in the Karma HTML reporter opened in your browser.

Ports and Services Summary

Service	URL	Notes
Angular Dev Server	`http://localhost:4200`	Started with `ng serve`
Spring Boot API	`http://localhost:8080`	Started with `mvn spring-boot:run`
PostgreSQL	`localhost:5432`	Default port; configured in `application.properties`

If port 4200 or 8080 is already in use on your machine, the respective server will fail to start. Use ng serve --port 4201 to change the Angular port, or set server.port=8081 in application.properties to change the backend port. If you change the backend port, you must also update every hardcoded http://localhost:8080 URL in the Angular component source files.

Setup & Deployment

API Reference

Quality & Compliance

Running BodegaX Locally: Frontend and Backend Setup

Running Tests

Ports and Services Summary

Build docs developers (and LLMs) love

Setup & Deployment

API Reference

Quality & Compliance

Documentation Index

​Running Tests

​Ports and Services Summary

Build docs developers (and LLMs) love

Running Tests

Ports and Services Summary