Installation - Inventory Management System

This guide provides comprehensive installation instructions for deploying the Inventory Management System in development and production environments.

System requirements

Backend requirements

Python: 3.8 or higher
Operating System: Linux, macOS, or Windows
Memory: Minimum 512MB RAM
Storage: 100MB for application and database

Frontend requirements

Node.js: 18.0 or higher
npm: 9.0 or higher (or yarn/pnpm equivalent)
Modern web browser: Chrome, Firefox, Safari, or Edge

Installation methods

Development
Production

Development installation

This setup is ideal for local development and testing.

Step 1: Clone the repository

git clone <your-repository-url>
cd inventory-management-system

Step 2: Backend setup

Create a virtual environment

cd backend
python -m venv venv

Activate the virtual environment:

source venv/bin/activate

Install dependencies

pip install -r requirements.txt

Key dependencies installed:

Flask 3.1.1 - Web framework
SQLAlchemy 2.0.41 - ORM for database operations
Flask-CORS 6.0.0 - Cross-origin resource sharing
Flask-JWT-Extended 4.7.1 - JWT authentication support
bcrypt 4.3.0 - Password hashing
python-dotenv 1.1.1 - Environment variable management

Database initialization

The database is automatically created when you first run the application:

python main.py

This will:

Create the SQLite database file inventory.db
Generate all required tables
Seed initial roles (admin, gestor, consultor)
Create the default admin user

The database file is created in the backend directory by default.

Step 3: Frontend setup

Install Node.js dependencies

cd frontend
npm install

Key dependencies:

React 19.2.0 - UI framework
Vite 7.3.1 - Build tool and dev server
Tailwind CSS 4.2.1 - Utility-first CSS framework

Start the development server

npm run dev

The application will be available at http://localhost:5173

Step 4: Verify installation

Check backend health

curl http://localhost:8000/api/health

Expected response:

{"status": "ok", "service": "inventory-api"}

Access the frontend

Open http://localhost:5173 and log in with:

Username: admin
Password: Admin1234!

Production installation

For production deployments, additional security and performance configurations are required.

Never use the default admin password in production. Change it immediately after initial setup.

Backend production setup

Install dependencies with production settings

pip install -r requirements.txt --no-dev

Configure environment variables

Create a .env file in the backend directory:

# Flask configuration
FLASK_ENV=production
SECRET_KEY=your-secure-secret-key-here

# Database
SQLALCHEMY_DATABASE_URL=sqlite:///./inventory.db

# Server
HOST=0.0.0.0
PORT=8000

# CORS (restrict to your frontend domain)
CORS_ORIGINS=https://your-frontend-domain.com

Generate a strong SECRET_KEY using:

python -c "import secrets; print(secrets.token_hex(32))"

Use a production WSGI server

Install Gunicorn:

pip install gunicorn

Run the application:

gunicorn -w 4 -b 0.0.0.0:8000 main:app

For production, use a process manager like systemd or supervisord.

Set up reverse proxy (recommended)

Configure Nginx as a reverse proxy:

server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Frontend production setup

Build the production bundle

cd frontend
npm run build

This creates an optimized production build in the dist directory.

Serve static files

Option 1: Use a static file server like Nginx:

server {
    listen 80;
    server_name yourdomain.com;
    root /path/to/frontend/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Option 2: Use the preview server for testing:

npm run preview

Configuration

Backend configuration

The backend is configured through backend/main.py and backend/Database/config.py.

Database configuration

By default, the system uses SQLite:

SQLALCHEMY_DATABASE_URL = "sqlite:///./inventory.db"

For production, you may want to use PostgreSQL or MySQL. Update the connection string in Database/config.py:

# PostgreSQL example
SQLALCHEMY_DATABASE_URL = "postgresql://user:password@localhost/inventory_db"

# MySQL example
SQLALCHEMY_DATABASE_URL = "mysql+pymysql://user:password@localhost/inventory_db"

Secret key configuration

The secret key is used for password reset tokens. In production, set this via environment variable:

app.config['SECRET_KEY'] = os.getenv('SECRET_KEY', 'your-fallback-secret')

CORS configuration

CORS is configured in main.py:31:

CORS(app, resources={r"/api/*": {"origins": "*"}})

For production, restrict origins:

CORS(app, resources={r"/api/*": {"origins": "https://your-domain.com"}})

Frontend configuration

The frontend uses Vite for building and development. Configuration is in frontend/vite.config.js.

API endpoint configuration

Update the API base URL in your API client configuration to point to your backend:

const API_BASE_URL = import.meta.env.PROD 
  ? 'https://api.yourdomain.com'
  : 'http://localhost:8000';

Database management

Automatic initialization

On first run, the application automatically:

Creates all database tables
Seeds three predefined roles:
- admin - Full system access
- gestor - Inventory management access
- consultor - Read-only access
Creates the default admin user

Manual database operations

The database schema is defined using SQLAlchemy models. Tables are created automatically via:

Base.metadata.create_all(bind=engine)

This runs in backend/main.py:27 on application startup.

Database migrations

For schema changes, you can use the alter_db.py script:

python alter_db.py

Always backup your database before running migrations:

cp inventory.db inventory.db.backup

Resetting the database

To start fresh with a clean database:

cd backend
rm inventory.db
python main.py

This will recreate the database with default data.

Initial user setup

The system automatically creates a default admin user:

Username: admin
Email: [email protected]
Password: Admin1234!
Role: admin

This is configured in the seeding logic in User/Domain/user_service.py.

Security Notice: Change the default admin password immediately after first login, especially in production environments.

To create additional users:

Log in as admin
Navigate to Users in the sidebar
Click Create User
Assign appropriate role (admin, gestor, or consultor)

Running the application

Development mode

cd backend
python main.py

Production mode

cd backend
gunicorn -w 4 -b 0.0.0.0:8000 main:app

Logging

The application includes comprehensive logging:

Location: backend/logs/
Format: Structured JSON logs with timestamps
Levels: DEBUG, INFO, WARNING, ERROR

Logs include:

API requests and responses
Authentication attempts
Database operations
Error traces

View logs:

tail -f backend/logs/app.log

Security considerations

Password hashing

Passwords are hashed using bcrypt with automatic salt generation

Role-based access

All endpoints are protected with role-based middleware

Audit logging

All system actions are logged for compliance

CORS protection

Configure allowed origins to prevent unauthorized access

Hardening checklist

Change default admin password
Set strong SECRET_KEY via environment variable
Configure restrictive CORS origins
Use HTTPS in production
Enable rate limiting on API endpoints
Regular database backups
Keep dependencies updated
Review audit logs regularly

Troubleshooting

Common issues

Import errors when starting backend

Ensure virtual environment is activated and dependencies are installed:

source venv/bin/activate
pip install -r requirements.txt

Database locked errors

SQLite has limitations with concurrent writes. For high-traffic environments, migrate to PostgreSQL or MySQL.

CORS errors in browser console

Verify the backend CORS configuration includes your frontend URL:

CORS(app, resources={r"/api/*": {"origins": "http://localhost:5173"}})

Port already in use

Change the port in main.py or kill the process using the port:

# Find process
lsof -i :8000
# Kill process
kill -9 <PID>

Frontend build fails

Clear node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install
npm run build

Health checks

The system provides health check endpoints for monitoring:

# API health
curl http://localhost:8000/api/health

# Root endpoint
curl http://localhost:8000/

Expected responses:

{"status": "ok", "service": "inventory-api"}
{"status": "ok", "message": "Inventory API is running (Flask)", "version": "1.0.0"}

Next steps

Quickstart Guide

Get started with the basics

API Documentation

Explore available endpoints

User Management

Set up roles and permissions

Deployment Guide

Deploy to production

For questions or issues, consult the application logs in backend/logs/ or review the source code documentation.

Getting Started

Core Features

User Management

Architecture

​System requirements

​Backend requirements

​Frontend requirements

​Installation methods

​Development installation

​Step 1: Clone the repository

​Step 2: Backend setup

​Step 3: Frontend setup

​Step 4: Verify installation

​Production installation

​Backend production setup

​Frontend production setup

​Configuration

​Backend configuration

​Database configuration

​Secret key configuration

​CORS configuration

​Frontend configuration

​API endpoint configuration

​Database management

​Automatic initialization

​Manual database operations

​Database migrations

​Resetting the database

​Initial user setup

​Running the application

​Development mode

​Production mode

​Logging

​Security considerations

Password hashing

Role-based access

Audit logging

CORS protection

​Hardening checklist

​Troubleshooting

​Common issues

​Health checks

​Next steps

Quickstart Guide

API Documentation

User Management

Deployment Guide

Build docs developers (and LLMs) love

System requirements

Backend requirements

Frontend requirements

Installation methods

Development installation

Step 1: Clone the repository

Step 2: Backend setup

Step 3: Frontend setup

Step 4: Verify installation

Production installation

Backend production setup

Frontend production setup

Configuration

Backend configuration

Database configuration

Secret key configuration

CORS configuration

Frontend configuration

API endpoint configuration

Database management

Automatic initialization

Manual database operations

Database migrations

Resetting the database

Initial user setup

Running the application

Development mode

Production mode

Logging

Security considerations

Hardening checklist

Troubleshooting

Common issues

Health checks

Next steps