Skip to main content

​
Installation Guide

This guide will walk you through installing Muebles Roble on your local machine. The entire process takes about 10-15 minutes.
Muebles Roble requires Python 3.10.11 specifically. Make sure you have the correct version installed before proceeding.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.10.11 installed
  • pip package manager (included with Python)
  • MySQL database server running
  • Git for cloning the repository
  • A terminal/command prompt

​
Verify Python Version

First, check that you have the correct Python version: 
python --version
You should see: 
Python 3.10.11
The application is tested with Python 3.10.11. Other versions may work but are not officially supported.

​
Verify pip Installation

pip --version
You should see output showing pip is installed with Python 3.10.

​
Installation Steps

1

Clone the Repository

Clone the Muebles Roble repository to your local machine:
git clone <URL_DEL_REPOSITORIO>
cd muebles-roble-diseno-app
Replace <URL_DEL_REPOSITORIO> with the actual repository URL provided by your team or instructor.
2

Create Virtual Environment

Create an isolated Python environment for the project:
python -m venv venv
This creates a venv/ directory containing a standalone Python installation.
Virtual environments prevent dependency conflicts between different Python projects.
3

Activate Virtual Environment

Activate the virtual environment based on your operating system:
venv\Scripts\activate
When activated successfully, you’ll see (venv) prefix in your terminal:
(venv) C:\Users\YourName\muebles-roble-diseno-app>
You need to activate the virtual environment every time you open a new terminal session to work on the project.
4

Install Dependencies

Install all required Python packages from requirements.txt:
pip install -r requirements.txt
This will install the following packages:
PackageVersionPurpose
Flask3.1.2Web framework
Flask-SQLAlchemy3.1.1ORM for database
Flask-Migrate4.1.0Database migrations
Flask-WTF1.2.2Form handling & CSRF
PyMySQL1.1.2MySQL driver
python-dotenv1.2.1Environment variables
WTForms3.2.1Form validation
SQLAlchemy2.0.46SQL toolkit
alembic1.18.4Migration tool
Plus development tools:
  • black - Code formatter
  • mypy - Type checker
The installation may take a few minutes depending on your internet connection.
5

Verify Installation

Verify that Flask is installed correctly:
flask --version
You should see output similar to:
Python 3.10.11
Flask 3.1.2
Werkzeug 3.1.5

​
Project Structure

After installation, your project directory should look like this: 
muebles-roble-diseno-app/
│
├── venv/                         # Virtual environment (created)
│   ├── Scripts/                  # Windows executables
│   ├── bin/                      # Unix executables
│   └── Lib/                      # Installed packages
│
├── app/                          # Application package
│   ├── __init__.py               # Flask app factory
│   ├── extensions.py             # Flask extensions
│   ├── exceptions.py             # Custom exceptions
│   │
│   ├── catalogs/                 # Catalog modules
│   │   ├── colors/
│   │   ├── wood_types/
│   │   ├── furniture_type/
│   │   ├── unit_of_measures/
│   │   └── roles/
│   │
│   ├── models/                   # Database models
│   │   ├── color.py
│   │   ├── wood_type.py
│   │   ├── furniture_type.py
│   │   ├── unit_of_measure.py
│   │   └── role.py
│   │
│   └── templates/                # Jinja2 templates
│       ├── base.html
│       └── colors/
│
├── docs/                         # Documentation
│   ├── ARCHITECTURE.md
│   └── CODING_CONVENTIONS.md
│
├── config.py                     # Configuration
├── run.py                        # Application entry point
├── requirements.txt              # Python dependencies
├── .env-template                 # Environment template
├── .gitignore                    # Git ignore rules
└── README.md                     # Project readme

​
Understanding Key Files

​
run.py - Entry Point

The run.py file is your application’s entry point: 
from app import create_app
from app.extensions import db

app = create_app()

# Test database connection
with app.app_context():
    try:
        connection = db.engine.connect()
        print("Database connection successful!")
        connection.close()
    except Exception as e:
        print(f"Database connection failed: {e}")

if __name__ == '__main__':
    app.run(debug=True)
This file:
  • Creates the Flask application using the factory pattern
  • Tests the database connection on startup
  • Runs the development server with debug mode enabled

​
config.py - Configuration

The config.py file manages all configuration: 
import os
from dotenv import load_dotenv

load_dotenv()

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")
        SECRET_KEY = "dev-secret-key-change-in-production"
Never commit your .env file to version control. It contains sensitive credentials.

​
requirements.txt - Dependencies

The complete dependency list: 
alembic==1.18.4
black==26.1.0
blinker==1.9.0
cffi==2.0.0
click==8.3.1
colorama==0.4.6
cryptography==46.0.5
Flask==3.1.2
Flask-Migrate==4.1.0
Flask-SQLAlchemy==3.1.1
Flask-WTF==1.2.2
greenlet==3.3.1
itsdangerous==2.2.0
Jinja2==3.1.6
librt==0.8.1
Mako==1.3.10
MarkupSafe==3.0.3
mypy==1.19.1
mypy_extensions==1.1.0
packaging==26.0
pathspec==1.0.4
platformdirs==4.9.2
psycopg2-binary==2.9.11
pycparser==3.0
PyMySQL==1.1.2
python-dotenv==1.2.1
pytokens==0.4.1
SQLAlchemy==2.0.46
sqlalchemy-stubs==0.4
tomli==2.4.0
types-Flask-SQLAlchemy==2.5.9.4
types-SQLAlchemy==1.4.53.38
typing_extensions==4.15.0
Werkzeug==3.1.5
WTForms==3.2.1

​
Common Installation Issues

Problem: python --version shows a different version.Solution: Install Python 3.10.11 from python.org and ensure it’s in your PATH. You may need to use python3.10 instead of python.
Problem: pip: command not foundSolution: Install pip using:
python -m ensurepip --upgrade
Problem: Script execution disabled on Windows.Solution: Run PowerShell as Administrator and execute:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Problem: Error installing PyMySQL or cryptography.Solution: Install build tools:
  • Windows: Install Microsoft C++ Build Tools
  • macOS: Install Xcode Command Line Tools: xcode-select --install
  • Linux: Install python3-dev and build-essential
Problem: Permission errors during installation.Solution: Ensure you’re in the virtual environment (you should see (venv) in your prompt). Never use sudo pip install.

​
Deactivating the Virtual Environment

When you’re done working on the project, deactivate the virtual environment: 
deactivate
The (venv) prefix will disappear from your prompt.

​
Next Steps

Configuration

Set up your database connection and environment variables

First Steps

Run the application and create your first catalog entries
Make sure to complete the Configuration Guide before attempting to run the application.

Build docs developers (and LLMs) love

Get started for freeTalk to us