Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DragonesMagicos/ferromax_v0.8/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the repository, configuring a local PostgreSQL database, and starting both the Spring Boot backend and the React frontend so you can log in and explore Ferromax ERP on your own machine. By the end you will have a fully functional instance running with seeded product data and two ready-to-use accounts.

​
Prerequisites

Ensure the following tools are installed and available on your PATH before you begin.
Java 17+ — The backend requires Java 17 or newer. Run java -version to confirm. Download from Adoptium if needed.
Maven 3.8+ — Used to build and run the Spring Boot application. Run mvn -version to confirm.
Node.js 18+ — Required by the Vite build toolchain. Run node -v to confirm. Download from nodejs.org if needed.
PostgreSQL 16 — The application targets PostgreSQL 16. Ensure the psql client is also available so you can run the database creation command.

​
Installation

1

Clone the repository

Clone the Ferromax repository to your local machine and enter the project directory.
git clone https://github.com/DragonesMagicos/ferromax_v0.8.git
cd ferromax_v0.8
2

Create the PostgreSQL database

Connect to your local PostgreSQL instance and create the application database.
CREATE DATABASE ferromax_db;
Hibernate’s ddl-auto=update strategy will create and migrate all tables automatically the first time the backend starts. You do not need to run any schema scripts manually.
3

Configure application.properties

Open src/main/resources/application.properties and replace the placeholder credentials with your local PostgreSQL username and password.
spring.datasource.url=jdbc:postgresql://localhost:5432/ferromax_db
spring.datasource.username=TU_USUARIO
spring.datasource.password=TU_PASSWORD
Never commit real credentials to version control. Consider using environment variables or a .env file excluded by .gitignore for team environments.
4

Start the backend

From the project root, build and start the Spring Boot application with Maven.
mvn spring-boot:run
The API server starts on port 8081 with base path /api. You should see a log line similar to:
Started FerromaxErpApplication in 4.2 seconds (process running for 4.8)
Hibernate will create all database tables on this first run. The data initializer will also seed the default admin and employee accounts.
5

Add product images

Product images are not included in the repository because of their size (~213 MB). Request the img.zip archive from your team and extract its contents into the frontend public directory.
ferromax-web/public/img/
The frontend references images by filename at this path. Without the images the application works normally — product cards will display broken image placeholders until the files are in place.
6

Install frontend dependencies and start the dev server

Open a second terminal, navigate to the ferromax-web directory, install Node dependencies, and start the Vite development server.
cd ferromax-web
npm install
npm run dev
The React SPA is served at http://localhost:5173. Vite’s hot-module replacement (HMR) is active by default, so source changes reflect immediately without a full page reload.
7

Log in and explore

Open http://localhost:5173 in your browser. Two accounts are available immediately after the first backend startup.
EmailPasswordAccess
[email protected]admin123Full ERP: dashboard, POS, inventory, remitos, stock adjustments, invoice OCR
[email protected]emp123Restricted ERP: POS terminal, product lookup, stock reception, pending orders
Log in as [email protected] first to see the full dashboard with KPIs and stock alerts. Then open a second browser window (or an incognito tab) as [email protected] to explore the employee-scoped POS view side by side.

​
Verify the Installation

Confirm the backend is running correctly by hitting the login endpoint directly with curl. 
curl -s -X POST http://localhost:8081/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"admin123"}' | jq
A successful response looks like this: 
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "rol": "ADMIN",
  "nombre": "José",
  "mensaje": "Login exitoso"
}
Copy the token value — you can pass it as Authorization: Bearer <token> in subsequent requests to test protected endpoints while the frontend is running.
The Invoice OCR feature (/ingreso-factura) requires Tesseract OCR to be installed on the host operating system and available on the system PATH. The application starts and functions fully without it, but image-based invoice scanning will fail with an error until Tesseract is present.

Build docs developers (and LLMs) love

Get started for freeTalk to us