Local Development and Production Deployment Setup Guide

This guide walks you through every step needed to run the Sistema de Inventario Tecnológico on your local machine for development, and then covers what must be changed before the system is ready for a production deployment. The application is split into two independent processes — an Express 5 backend on port 3001 and a Vite-powered React frontend on port 5173 — so you will start both separately.

Local Development Setup

Prerequisites

Make sure the following are available on your machine before continuing:

Node.js 18 or later — required by both the backend (ES module syntax, crypto, fs/promises) and the frontend build tooling. Verify with node --version.
pnpm (recommended) or npm — used to install dependencies in each workspace. Install pnpm globally with npm install -g pnpm.
A Firebase project with Firestore enabled — the backend stores all inventory records (equipos, periféricos, ubicaciones, bitácora) in Firestore. Create a project at console.firebase.google.com and enable Cloud Firestore in Native mode.
A MySQL database — used exclusively for user accounts and password-reset token storage. MySQL 8+ is recommended.
SMTP access via Gmail — the password-recovery flow sends emails through Gmail’s SMTP service. You need a Gmail account with an App Password generated (see the Environment Variables page for details).

Clone the repository

Clone the project from GitHub and move into the root directory:

git clone https://github.com/Danielings/Pasantia-Proyecto.git
cd Pasantia-Proyecto

Set up the backend

Install backend dependencies and create your local environment file:

cd backend
pnpm install
cp .env.example .env

Open backend/.env in your editor and fill in every value. Refer to the Environment Variables reference for a description of each variable. At minimum you need the six Firebase service-account fields, JWT_SECRET, SMTP_USER, SMTP_PASS, and the four DB_* variables for MySQL.

The pnpm install step installs all runtime dependencies declared in backend/package.json, including express, firebase-admin, jsonwebtoken, nodemailer, mysql2, bcrypt, pdfkit, and xlsx. No global CLI tools beyond Node.js and pnpm are required.

Configure Firebase

The backend authenticates with Firestore using a service account private key. To obtain one:

Open the Firebase console and select your project.
Go to Project Settings (the gear icon) → Service accounts tab.
Click Generate new private key and confirm. A JSON file is downloaded to your machine.
Open the downloaded JSON and copy the following fields into your backend/.env:

JSON field	`.env` variable
`project_id`	`project_id`
`private_key_id`	`private_key_id`
`private_key`	`private_key`
`client_email`	`client_email`
`client_id`	`client_id`
`client_x509_cert_url`	`client_x509_cert_url`

When pasting private_key into .env, keep the entire value on one line inside double quotes, with \n representing each newline — for example:

private_key="-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----\n"

The backend calls .replace(/\\n/g, "\n") at startup to restore the real newline characters before passing the key to firebase-admin.

Delete the downloaded service account JSON file after copying the values, or store it in a secure secrets manager. Anyone who obtains this file has full administrative access to your Firestore database.

Start the backend

From the backend/ directory, start the Express server:

node index.js

The server listens on http://localhost:3001. On a successful start you will see output similar to:

[env] 11 variables cargadas desde .env
Existe conexión

The first line confirms dotenv loaded your .env file. The second confirms the MySQL connection pool established a test connection. If MySQL is unreachable the server still starts, but any route that reads from MySQL will fail at runtime.

Set up the frontend

In a new terminal, move to the frontend/ directory, install dependencies, and start the Vite development server:

cd ../frontend
pnpm install
pnpm dev

Vite starts on http://localhost:5173 with Hot Module Replacement enabled. The @ path alias resolves to frontend/src/, so imports like import { api } from "@/lib/api" work without any additional configuration.

The backend’s CORS policy in backend/index.js explicitly allows requests from http://localhost:5173. If you change the Vite port (via --port), you must update the origin value in index.js to match, or the browser will block all API calls with a CORS error.

Seed geographic data

The location selectors in the UI (region, estado, ciudad) are populated from three Firestore collections: regiones, estados, and ciudades. These collections are not created automatically — they must be populated before the location dropdowns will display any options.You can seed the data in two ways:

Firebase console — navigate to Firestore Database, create each collection manually, and add documents following the data shape expected by the ubicacion API (backend/apis/ubicacion.js).
Seed script — if the project includes a seed or migration script in backend/scripts/, run it with node backend/scripts/<script-name>.js after the server has started and the Firebase credentials are confirmed to be working.

All other collections (equipos, perifericos, usuarios, bitacora, ubicaciones) are created on demand when the first document is written through the API. Only the geographic reference collections require up-front seeding.

Production Checklist

Before exposing the application to end users, work through each item below. Every item addresses a concrete security or reliability risk that exists in the default development configuration.

Enable secure cookies (HTTPS required)

JWT access tokens are stored in HTTP-only cookies. In development the cookie is set without secure: true, which allows it to be sent over plain HTTP. In production the server must be behind HTTPS and the cookie option must be updated to secure: true so the browser refuses to transmit the cookie over unencrypted connections.Locate the res.cookie(...) call in backend/apis/usuarios.js and add the flag:

res.cookie("acceso_token", token, {
  httpOnly: true,
  secure: true,        // add this line
  sameSite: "strict",
  maxAge: 1000 * 60 * 60 * 8,
});

Set JWT_SECRET to a cryptographically random value

The backend falls back to the hard-coded string "lol" when JWT_SECRET is absent. An attacker who knows this default can mint valid tokens and authenticate as any user. Generate a proper secret with:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Set the output as JWT_SECRET in your production environment and ensure the variable is never stored in source control.

Update CORS to the production frontend URL

The CORS policy in backend/index.js is hard-coded to http://localhost:5173:

app.use(
  cors({
    origin: "http://localhost:5173",   // ← change this
    credentials: true,
    // ...
  })
);

Change the origin value to your production frontend domain (e.g. https://inventario.example.com). Leaving it as localhost will cause every browser request from the production frontend to be rejected with a CORS error.

Build the frontend and serve the dist/ folder

The Vite development server (pnpm dev) is not suitable for production. Build the optimised static bundle from the frontend/ directory:

cd frontend
pnpm build

The output is written to frontend/dist/. Serve this folder with a static file server or CDN — for example Nginx, Caddy, Vercel, or Netlify. Make sure your server is configured to rewrite all routes to index.html so that React Router’s client-side navigation works correctly.

Set FRONTEND_URL to the production domain

The backend constructs password-reset links using the FRONTEND_URL environment variable and falls back to http://localhost:5173. In production, set this to the publicly accessible URL of your frontend:

FRONTEND_URL=https://inventario.example.com

An incorrect value here means password-reset emails will contain links that point to localhost, which will not work for end users.

Use PM2 (or equivalent) to manage the Node.js process

Running the backend with node index.js means the process exits on any unhandled error and does not restart after a server reboot. Use a process manager to keep it running reliably.

# Install PM2 globally
npm install -g pm2

# Start the backend
cd backend
pm2 start index.js --name inventario-backend

# Persist across reboots
pm2 save
pm2 startup

PM2 also provides built-in log management (pm2 logs) and monitoring (pm2 monit).

Configure MySQL with production credentials

The DB_USER / DB_PASSWORD values used locally (often root with a weak password) should be replaced in production with a dedicated database user that has only the minimum required privileges (SELECT, INSERT, UPDATE, DELETE) on the inventario database and nothing else.

CREATE USER 'inventario_app'@'localhost' IDENTIFIED BY '<strong-password>';
GRANT SELECT, INSERT, UPDATE, DELETE ON inventario.* TO 'inventario_app'@'localhost';
FLUSH PRIVILEGES;

Update DB_USER, DB_PASSWORD, and DB_HOST in the production environment to reflect the new credentials. Never use the root account in a production application.

Getting Started

Core Features

User Management

Deployment

Local Development Setup

Production Checklist

Build docs developers (and LLMs) love

Getting Started

Core Features

User Management

Deployment

Documentation Index

​Local Development Setup

​Production Checklist

Build docs developers (and LLMs) love

Local Development Setup

Production Checklist