Installation

This guide provides detailed installation instructions for setting up the Furniture Store Backend on all major platforms.

Prerequisites

Before you begin, ensure you have the following installed:

Python 3.10.11

The exact Python version required for this project

MySQL 8.0+

Relational database for storing application data

pip

Python package manager (included with Python)

Git

Version control system for cloning the repository

Verify Python Installation

Check that you have the correct Python version installed:

python --version

You should see:

Python 3.10.11

This project requires Python 3.10.11 specifically. Other versions may cause compatibility issues with dependencies.

Installing Python 3.10.11

If you don’t have Python 3.10.11 installed:

Windows
macOS
Linux

Download Python 3.10.11 from python.org
Run the installer
Check “Add Python to PATH”
Click “Install Now”
Verify installation: python --version

Using Homebrew:

brew install [email protected]

Or download from python.org

Using deadsnakes PPA (Ubuntu/Debian):

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-dev

MySQL Installation

The Furniture Store Backend uses MySQL as its database system.

Windows
macOS
Linux

Download MySQL Community Server from mysql.com
Run the installer and choose “Developer Default”
Set a root password during installation
Complete the installation wizard
Verify: Open MySQL Workbench or run mysql --version

Using Homebrew:

brew install mysql
brew services start mysql
mysql_secure_installation

sudo apt update
sudo apt install mysql-server
sudo systemctl start mysql
sudo mysql_secure_installation

Make note of your MySQL root password - you’ll need it for database configuration.

Installation Steps

1. Clone the Repository

Clone the project from your version control system:

git clone <URL_DEL_REPOSITORIO>
cd backend-muebleria

2. Create Virtual Environment

A virtual environment isolates project dependencies from your system Python installation.

python -m venv venv

This creates a venv directory containing an isolated Python environment.

3. Activate Virtual Environment

venv\Scripts\activate

When successfully activated, your terminal prompt will show (venv) at the beginning.

To deactivate later, simply run:

deactivate

4. Install Dependencies

With the virtual environment activated, install all required packages:

pip install -r requirements.txt

This installs the following key dependencies:

requirements.txt

Flask==3.1.2
Flask-SQLAlchemy==3.1.1
Flask-Migrate==4.1.0
Flask-WTF==1.2.2
PyMySQL==1.1.2
SQLAlchemy==2.0.46
WTForms==3.2.1
python-dotenv==1.2.1
alembic==1.18.4

View all dependencies

The complete list includes:

Flask (3.1.2) - Web framework
Flask-SQLAlchemy (3.1.1) - ORM integration
Flask-Migrate (4.1.0) - Database migrations
Flask-WTF (1.2.2) - Form handling and CSRF protection
PyMySQL (1.1.2) - MySQL database driver
SQLAlchemy (2.0.46) - SQL toolkit and ORM
WTForms (3.2.1) - Form validation
python-dotenv (1.2.1) - Environment variable management
alembic (1.18.4) - Database migration tool
black (26.1.0) - Code formatter
mypy (1.19.1) - Static type checker

5. Environment Configuration

Create your environment configuration file:

cp .env-template .env

Edit the .env file with your specific configuration:

.env

FLASK_APP=app.py
FLASK_ENV=development

DB_USER=your_mysql_username
DB_PASSWORD=your_mysql_password
DB_HOST=localhost
DB_PORT=3306
DB_NAME=furniture_store_db

Security Best Practices:

Never commit the .env file to version control
Use strong passwords for production databases
The .env file is already in .gitignore

Understanding the Configuration

The application uses these environment variables in config.py:

config.py

class Config:
    DB_USER = os.getenv("DB_USER")
    DB_PASSWORD = os.getenv("DB_PASSWORD")
    DB_HOST = os.getenv("DB_HOST")
    DB_PORT = os.getenv("DB_PORT")
    DB_NAME = os.getenv("DB_NAME")

    SQLALCHEMY_DATABASE_URI = (
        f"mysql+pymysql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
    )

    SQLALCHEMY_TRACK_MODIFICATIONS = False

    SECRET_KEY = os.getenv("SECRET_KEY")
    if not SECRET_KEY:
        if os.getenv("FLASK_ENV") == "production":
            raise ValueError("SECRET_KEY must be set in production environment")
        SECRET_KEY = "dev-secret-key-change-in-production"

6. Database Initialization

Create the Database

Connect to MySQL and create the application database:

mysql -u root -p

Then in the MySQL prompt:

CREATE DATABASE furniture_store_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
GRANT ALL PRIVILEGES ON furniture_store_db.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Or create it directly from the command line:

mysql -u root -p -e "CREATE DATABASE furniture_store_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

Run Migrations

Initialize the database schema using Flask-Migrate:

flask db upgrade

This executes all migration files to create the database structure:

What tables are created?

The migrations create the following tables:

colors - Color catalog (Natural, White, Black, etc.)
wood_types - Wood type catalog (Pine, Cedar, Oak, etc.)
furniture_types - Furniture catalog (Tables, Chairs, Closets, etc.)
roles - User roles and permissions
unit_of_measures - Units of measurement (kg, m, pieces, etc.)

Each table includes:

Primary key (id_*)
Timestamps (created_at, updated_at, deleted_at)
Audit fields (created_by, updated_by, deleted_by)
Soft delete support (active boolean)

7. Verify Installation

Start the development server:

python run.py

You should see:

Database connection successful!
 * Serving Flask app 'app'
 * Debug mode: on
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit

The application automatically tests the database connection on startup (see run.py:6-13).

Test the Application

Open your browser and navigate to:

http://127.0.0.1:5000/colors/

You should see the colors catalog page.

Run a Test Request

Create a test color using curl:

curl -X POST http://127.0.0.1:5000/colors/create \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Test Color"

If successful, you’ll receive a redirect response with a success message.

Project Structure

After installation, your project structure will look like this:

backend-muebleria/
├── app/                          # Application package
│   ├── __init__.py               # Flask app factory
│   ├── extensions.py             # Flask extensions (SQLAlchemy, Migrate, CSRF)
│   ├── exceptions.py             # Custom exceptions
│   ├── catalogs/                 # Catalog modules
│   │   ├── colors/
│   │   │   ├── routes.py         # Color endpoints
│   │   │   ├── services.py       # Business logic
│   │   │   └── forms.py          # WTForms definitions
│   │   ├── wood_types/
│   │   ├── furniture_type/
│   │   ├── roles/
│   │   └── unit_of_measures/
│   ├── models/                   # Database models
│   │   ├── color.py
│   │   ├── wood_type.py
│   │   ├── furniture_type.py
│   │   ├── role.py
│   │   └── unit_of_measure.py
│   └── templates/                # Jinja2 templates
├── migrations/                   # Database migrations
│   └── versions/
├── config.py                     # Application configuration
├── run.py                        # Application entry point
├── requirements.txt              # Python dependencies
├── .env                          # Environment variables (create this)
├── .env-template                 # Environment template
└── .python-version               # Python version specification

Next Steps

Quickstart Guide

Make your first API request in 5 minutes

Architecture Overview

Understand the MVC layered architecture

API Reference

Explore available endpoints and their usage

Development Guide

Learn coding conventions and best practices

Troubleshooting

Python version mismatch

If you have multiple Python versions installed, specify the version explicitly:

python3.10 -m venv venv

Or use pyenv to manage Python versions:

pyenv install 3.10.11
pyenv local 3.10.11

MySQL connection errors

Common issues:

Authentication failed: Verify username and password in .env

Cannot connect: Ensure MySQL service is running

# Windows
net start MySQL

# macOS
brew services start mysql

# Linux
sudo systemctl start mysql

Database doesn’t exist: Create the database first (see step 6)

pip install fails

If you encounter errors during pip install:

Upgrade pip:
```
pip install --upgrade pip
```

Install build dependencies (Linux):

sudo apt install python3.10-dev build-essential

Install packages individually to identify the problem:

pip install Flask Flask-SQLAlchemy Flask-Migrate

Migration errors

If flask db upgrade fails:

Check database connection:

mysql -u your_user -p -e "SHOW DATABASES;"

Verify the database exists and is accessible
Check migration history:
```
flask db current
flask db history
```

If needed, recreate the database:

mysql -u root -p -e "DROP DATABASE furniture_store_db;"
mysql -u root -p -e "CREATE DATABASE furniture_store_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
flask db upgrade

Port 5000 already in use

If port 5000 is occupied, specify a different port:

flask run --port 5001

Or set it in .env:

FLASK_RUN_PORT=5001

Import errors

Ensure you’re in the correct directory and virtual environment is activated:

# Check you're in the project root
pwd  # or cd on Windows

# Verify virtual environment is active
which python  # or where python on Windows

# Should show path to venv/bin/python

Additional Resources

Flask Documentation

Official Flask documentation

SQLAlchemy

Learn about the ORM

MySQL Docs

MySQL reference manual

Get Started

Core Concepts

Configuration

Prerequisites

Python 3.10.11

MySQL 8.0+

pip

Git

Verify Python Installation

Installing Python 3.10.11

MySQL Installation

Installation Steps

1. Clone the Repository

2. Create Virtual Environment

3. Activate Virtual Environment

4. Install Dependencies

5. Environment Configuration

Understanding the Configuration

6. Database Initialization

Create the Database

Run Migrations

7. Verify Installation

Test the Application

Run a Test Request

Project Structure

Next Steps

Quickstart Guide

Architecture Overview

API Reference

Development Guide

Troubleshooting

Additional Resources

Flask Documentation

SQLAlchemy

MySQL Docs

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

​Prerequisites

Python 3.10.11

MySQL 8.0+

pip

Git

​Verify Python Installation

​Installing Python 3.10.11

​MySQL Installation

​Installation Steps

​1. Clone the Repository

​2. Create Virtual Environment

​3. Activate Virtual Environment

​4. Install Dependencies

​5. Environment Configuration

​Understanding the Configuration

​6. Database Initialization

​Create the Database

​Run Migrations

​7. Verify Installation

​Test the Application

​Run a Test Request

​Project Structure

​Next Steps

Quickstart Guide

Architecture Overview

API Reference

Development Guide

​Troubleshooting

​Additional Resources

Flask Documentation

SQLAlchemy

MySQL Docs

Build docs developers (and LLMs) love

Prerequisites

Verify Python Installation

Installing Python 3.10.11

MySQL Installation

Installation Steps

1. Clone the Repository

2. Create Virtual Environment

3. Activate Virtual Environment

4. Install Dependencies

5. Environment Configuration

Understanding the Configuration

6. Database Initialization

Create the Database

Run Migrations

7. Verify Installation

Test the Application

Run a Test Request

Project Structure

Next Steps

Troubleshooting

Additional Resources