Installation Guide

This guide provides detailed instructions for installing and configuring Sistema de Productos on your system. Follow these steps for a complete setup from prerequisites through production deployment.

Prerequisites

Before installing Sistema de Productos, ensure your system meets these requirements:

Node.js

Required Version: Node.js 18.x or higher (tested with v24.13.1)

Check Current Version

Verify your Node.js installation:

node --version

If the version is below 18.x or Node.js is not installed, proceed to the next step.

Install Node.js

Download and install Node.js from nodejs.org

brew install node

Verify Installation

Confirm Node.js and npm are installed:

node --version
npm --version

PostgreSQL

Required Version: PostgreSQL 12.x or higher

Install PostgreSQL

brew install postgresql@15
brew services start postgresql@15

Verify PostgreSQL is Running

# Check if PostgreSQL is running
pg_isready

# Expected output:
# /var/run/postgresql:5432 - accepting connections

Set PostgreSQL Password

# Connect to PostgreSQL
sudo -u postgres psql

-- Set password for postgres user
ALTER USER postgres PASSWORD 'your_secure_password';

-- Exit psql
\q

Git (Optional)

Required for: Cloning the repository

# Verify Git installation
git --version

# Install if needed
# macOS (Homebrew)
brew install git

# Ubuntu/Debian
sudo apt install git

# Windows (Chocolatey)
choco install git

Installation Steps

1. Download the Project

git clone <repository-url>
cd proyectico-vue-express

2. Install Dependencies

Install all required npm packages:

npm install

This will install the following key dependencies:

Frontend Dependencies

[email protected] - Progressive JavaScript framework
[email protected] - Official router for Vue.js
[email protected] - State management library
[email protected] - HTTP client for API requests
[email protected] - Utility-first CSS framework

Backend Dependencies

[email protected] - Web application framework
[email protected] - PostgreSQL client for Node.js
[email protected] - JWT authentication
[email protected] - Password hashing
[email protected] - Cross-origin resource sharing
[email protected] - Cookie parsing middleware
[email protected] - Email sending functionality

Development Dependencies

[email protected] - Frontend build tool
[email protected] - Auto-restart for backend development
[email protected] - Run multiple commands simultaneously
[email protected] - Environment variable management

Troubleshooting npm install

If you encounter issues during installation:Error: EACCES permission denied

# Fix npm permissions (Linux/macOS)
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Error: node-gyp build failed

# Install build tools
# Ubuntu/Debian
sudo apt-get install build-essential

# macOS
xcode-select --install

# Windows
npm install --global windows-build-tools

Network or timeout errors

# Clear npm cache
npm cache clean --force

# Try with different registry
npm install --registry=https://registry.npmjs.org/

3. Database Setup

Create Database

Connect to PostgreSQL and create the database:

# Connect to PostgreSQL
psql -U postgres

-- Create the database
CREATE DATABASE ejercicio_productos;

-- Verify database was created
\l

-- Exit psql
\q

Run Schema Script

Execute the database schema file to create tables, views, and sample data:

psql -U postgres -d ejercicio_productos -f server/config/bd.sql

This creates:

3 Tables: Categorias, Productos, Usuarios
3 Views: ProductosView, CategoriasView, UsuariosView
Extension: pgcrypto for password encryption
Sample Data: 4 categories and 19 products
Admin User: Default administrator account

Verify Database Setup

Confirm tables were created successfully:

psql -U postgres -d ejercicio_productos

-- List all tables
\dt

-- Should show: categorias, productos, usuarios

-- Check sample data
SELECT COUNT(*) FROM Categorias;
SELECT COUNT(*) FROM Productos;
SELECT COUNT(*) FROM Usuarios;

-- Exit
\q

Expected counts:

Categorias: 4 rows
Productos: 19 rows
Usuarios: 1 row (admin user)

Database Schema Details

The database includes the following structure:Tables:

-- Categories with visual properties
CREATE TABLE Categorias (
  id SERIAL PRIMARY KEY,
  nombre VARCHAR(50) NOT NULL UNIQUE,
  icono VARCHAR(50) NOT NULL,
  color VARCHAR(50) NOT NULL,
  descripcion TEXT,
  creado TIMESTAMP NOT NULL,
  actualizado TIMESTAMP 
);

-- Products with pricing and inventory
CREATE TABLE Productos (
  id SERIAL PRIMARY KEY,
  nombre VARCHAR(100) NOT NULL UNIQUE,
  precio DECIMAL(10, 2) NOT NULL,
  stock INT NOT NULL DEFAULT(0),
  descripcion TEXT,
  creado TIMESTAMP NOT NULL,
  actualizado TIMESTAMP,
  idCategoria INT REFERENCES Categorias(id) NOT NULL
);

-- Users with role-based access
CREATE TABLE Usuarios (
  id SERIAL PRIMARY KEY,
  nombre VARCHAR(20) NOT NULL UNIQUE,
  contrasena TEXT NOT NULL,
  correo VARCHAR(50) NOT NULL,
  rol VARCHAR(20) NOT NULL,
  creado TIMESTAMP NOT NULL,
  actualizado TIMESTAMP
);

Views provide formatted date/time fields for easier frontend consumption.

4. Environment Configuration

Create and configure the environment variables file:

Create .env File

touch .env

Add Configuration

Open .env in your text editor and add the following:

# ===================
# Server Configuration
# ===================
PORT=3000

# ===================
# PostgreSQL Database
# ===================
PG_USER=postgres
PG_HOST=localhost
PG_DATABASE=ejercicio_productos
PG_PASSWORD=your_postgres_password_here
PG_PORT=5432

# ===================
# JWT Authentication
# ===================
# Generate a secure random string (see below)
JWT_SECRET=your_jwt_secret_key_here

# ===================
# Email Configuration
# ===================
# Optional: for nodemailer functionality
EMAIL_USER=[email protected]
EMAIL_PASSWORD=your_email_app_password

Generate Secure JWT Secret

Create a cryptographically secure JWT secret:

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

Copy the output and replace your_jwt_secret_key_here in your .env file.

Verify Configuration

Ensure all required variables are set:

# Check .env file exists and has content
cat .env

Never commit .env to version control. The file is already listed in .gitignore.

5. Start the Application

Run the development servers:

npm run dev

This command starts:

Frontend (Vite): http://localhost:5173
Backend (Express): http://localhost:3000

Expected console output:

[0] 
[0]   VITE v7.1.0  ready in 450 ms
[0] 
[0]   ➜  Local:   http://localhost:5173/
[0]   ➜  Network: http://192.168.1.x:5173/
[1] API funcionando en el puerto 3000.
[1] Base de datos conectada.

Configuration Details

Backend Server Configuration

The backend is configured in server/index.js and server/app.js:

// server/index.js
import app from './app.js';
import 'dotenv/config';

const port = process.env.PORT;

app.listen(port, () => {
  console.log(`API funcionando en el puerto ${port}.`);
});

// server/app.js
import express from 'express';
import cookieParser from 'cookie-parser';
import cors from 'cors';
import router from './routes/index.js';

const app = express();

app.use(cors({
  origin: 'http://localhost:5173',
  credentials: true
}));

app.use(express.json());
app.use(cookieParser());
app.use('/api-productos', router);

export default app;

Database Connection Configuration

Database connection is managed in server/config/database.js:

import { Pool } from 'pg';
import 'dotenv/config';

const pool = new Pool({
  user: process.env.PG_USER || 'postgres',
  host: process.env.PG_HOST || 'localhost',
  database: process.env.PG_DATABASE || 'ejercicio_productos',
  password: process.env.PG_PASSWORD || 'tu_contraseña',
  port: process.env.PG_PORT || 5432,
});

pool.connect((error) => {
  if(error) throw error;
  console.log('Base de datos conectada.');
});

export default pool;

Frontend Configuration

Vite configuration in vite.config.js:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    vue(),
    tailwindcss(),
  ],
});

Production Deployment

Build for Production

Build Frontend

npm run build

This creates an optimized production build in the dist/ directory.

Set Production Environment Variables

Update .env for production:

NODE_ENV=production
PORT=80

# Use production database
PG_HOST=your-production-db-host
PG_DATABASE=ejercicio_productos_prod
PG_PASSWORD=strong_production_password

# Strong JWT secret
JWT_SECRET=long_random_production_secret

Serve Static Files

Configure Express to serve the built frontend:

// Add to server/app.js
import path from 'path';

// Serve static files in production
if (process.env.NODE_ENV === 'production') {
  app.use(express.static(path.join(__dirname, '../dist')));
  
  app.get('*', (req, res) => {
    res.sendFile(path.join(__dirname, '../dist/index.html'));
  });
}

Use Process Manager

Use PM2 to manage the Node.js process:

# Install PM2 globally
npm install -g pm2

# Start the application
pm2 start server/index.js --name "sistema-productos"

# Configure PM2 to start on system boot
pm2 startup
pm2 save

Production Security Checklist:

Use strong, unique passwords for database and JWT secret
Enable HTTPS/SSL for encrypted communication
Configure proper CORS origins (not localhost)
Set up database backups
Implement rate limiting on API endpoints
Change default admin password
Use environment-specific .env files
Enable PostgreSQL SSL connections

Verification and Testing

Test API Endpoints

# Test API health
curl http://localhost:3000/api-productos

# Expected: "API funcionando correctamente."

# Test categories endpoint (requires auth)
curl http://localhost:3000/api-productos/categorias

Test Frontend Access

Open browser to http://localhost:5173
You should see the login page
Login with default credentials:
- Username: admin01
- Password: Admin01*

Verify Database Connection

Check backend console output:

Base de datos conectada.
API funcionando en el puerto 3000.

Troubleshooting

Database Connection Errors

Error: Connection refused or could not connect to serverSolutions:

Verify PostgreSQL is running:

pg_isready
sudo systemctl status postgresql

Check PostgreSQL is listening on the correct port:
```
sudo netstat -plunt | grep postgres
```
Verify .env database credentials are correct

Check PostgreSQL allows local connections:

# Edit pg_hba.conf
sudo nano /etc/postgresql/*/main/pg_hba.conf

# Ensure this line exists:
host    all             all             127.0.0.1/32            md5

# Restart PostgreSQL
sudo systemctl restart postgresql

Test manual connection:

psql -U postgres -h localhost -d ejercicio_productos

Port Already in Use

Error: EADDRINUSE: address already in useSolutions:

Find process using the port:

# For port 3000
lsof -i :3000

# For port 5173
lsof -i :5173

Kill the process:
```
kill -9 <PID>
```
Or change the port in .env:
```
PORT=3001
```

Module Import Errors

Error: Cannot find module or ERR_MODULE_NOT_FOUNDSolutions:

Verify package.json has "type": "module"

Ensure all imports use .js extensions:

// Correct
import pool from './config/database.js';

// Incorrect
import pool from './config/database';

Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Check Node.js version (must be 18+):
```
node --version
```

JWT Token Errors

Error: jwt malformed or invalid tokenSolutions:

Verify JWT_SECRET is set in .env
Clear browser cookies and try logging in again
Check cookies are enabled in browser

Verify CORS settings allow credentials:

app.use(cors({
  origin: 'http://localhost:5173',
  credentials: true  // Must be true
}));

Frontend Build Errors

Error: Build failures or Vite errorsSolutions:

Clear Vite cache:
```
rm -rf node_modules/.vite
```
Verify all Vue files have correct syntax
Check for circular dependencies
Rebuild:
```
npm run build
```

bcrypt Installation Issues

Error: bcrypt fails to install or buildSolutions:

Install build tools:

# Ubuntu/Debian
sudo apt-get install build-essential python3

# macOS
xcode-select --install

# Windows
npm install --global windows-build-tools

Rebuild bcrypt:
```
npm rebuild bcrypt --build-from-source
```
Or use bcryptjs as alternative (update package.json)

Default Admin Account

The database setup creates a default administrator account:

Username: admin01
Password: Admin01*
Email: [email protected]
Role: Administrador

Security: Change the default administrator password immediately, especially before deploying to production.

To change the password, log in and use the user management interface, or update directly in the database:

-- Update password (hashed with bcrypt)
UPDATE Usuarios 
SET contrasena = crypt('NewSecurePassword123!', gen_salt('bf'))
WHERE nombre = 'admin01';

Next Steps

Your installation is complete! Here’s what to do next:

Explore the Application: Log in and familiarize yourself with the interface
Review the Code: Examine the project structure and implementation
Customize: Modify categories, add products, create users
API Testing: Use Postman or curl to test API endpoints
Development: Start building new features or modifications

For a quick overview of features and usage, refer back to the Introduction page.

Get Started

Core Concepts

Frontend Guide

Guides

Installation

Installation Guide

Prerequisites

Node.js

PostgreSQL

Git (Optional)

Installation Steps

1. Download the Project

2. Install Dependencies

Frontend Dependencies

Backend Dependencies

Development Dependencies

3. Database Setup

4. Environment Configuration

5. Start the Application

Configuration Details

Backend Server Configuration

Database Connection Configuration

Frontend Configuration

Production Deployment

Build for Production

Verification and Testing

Test API Endpoints

Test Frontend Access

Verify Database Connection

Troubleshooting

Default Admin Account

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Concepts

Frontend Guide

Guides

​Installation Guide

​Prerequisites

​Node.js

​PostgreSQL

​Git (Optional)

​Installation Steps

​1. Download the Project

​2. Install Dependencies

​Frontend Dependencies

​Backend Dependencies

​Development Dependencies

​3. Database Setup

​4. Environment Configuration

​5. Start the Application

​Configuration Details

​Backend Server Configuration

​Database Connection Configuration

​Frontend Configuration

​Production Deployment

​Build for Production

​Verification and Testing

​Test API Endpoints

​Test Frontend Access

​Verify Database Connection

​Troubleshooting

​Default Admin Account

​Next Steps

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Node.js

PostgreSQL

Git (Optional)

Installation Steps

1. Download the Project

2. Install Dependencies

Frontend Dependencies

Backend Dependencies

Development Dependencies

3. Database Setup

4. Environment Configuration

5. Start the Application

Configuration Details

Backend Server Configuration

Database Connection Configuration

Frontend Configuration

Production Deployment

Build for Production

Verification and Testing

Test API Endpoints

Test Frontend Access

Verify Database Connection

Troubleshooting

Default Admin Account

Next Steps