Configuration Guide

Before running Muebles Roble, you need to configure the database connection and set up environment variables. This guide walks you through the complete configuration process.

All sensitive configuration data is stored in environment variables using a .env file, never hard-coded in the application.

Environment Variables Setup

Locate the Template File

The project includes a .env-template file that serves as a reference for all required environment variables:

# .env-template
FLASK_APP=app.py
FLASK_ENV=development

DB_USER=example_user
DB_PASSWORD=example_password
DB_HOST=localhost
DB_PORT=3306
DB_NAME=example_db

Do NOT delete the .env-template file. It serves as documentation for required variables.

Create Your .env File

Copy the template to create your actual environment file:

cp .env-template .env

On Windows (Command Prompt):

copy .env-template .env

On Windows (PowerShell):

Copy-Item .env-template .env

Configure Database Variables

Open the .env file in your text editor and update the database credentials:

# Flask Configuration
FLASK_APP=app.py
FLASK_ENV=development

# Database Configuration
DB_USER=your_mysql_username
DB_PASSWORD=your_mysql_password
DB_HOST=localhost
DB_PORT=3306
DB_NAME=muebles_roble_db

Replace the values with your actual MySQL credentials.

Add Secret Key (Optional but Recommended)

For production or better security, add a SECRET_KEY:

# Add this line to your .env file
SECRET_KEY=your-secret-key-here-make-it-random-and-long

Generate a secure secret key using Python:

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

In development, the app will use a default secret key if you don’t set one. In production, it’s required.

Environment Variables Reference

Flask Variables

Variable	Required	Default	Description
`FLASK_APP`	No	`app.py`	Entry point for Flask CLI commands
`FLASK_ENV`	No	`production`	Environment mode: `development` or `production`
`SECRET_KEY`	Production only	`dev-secret-key...`	Secret key for session management and CSRF protection

Database Variables

Variable	Required	Example	Description
`DB_USER`	Yes	`root`	MySQL database username
`DB_PASSWORD`	Yes	`mypassword`	MySQL database password
`DB_HOST`	Yes	`localhost`	Database server hostname or IP
`DB_PORT`	Yes	`3306`	MySQL server port (default: 3306)
`DB_NAME`	Yes	`muebles_roble_db`	Name of the database to use

Configuration File Structure

The config.py file loads and processes these environment variables:

import os
from dotenv import load_dotenv

load_dotenv()  # Load variables from .env file

class Config:
    # Database configuration from environment
    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")
    
    # Construct SQLAlchemy database URI
    SQLALCHEMY_DATABASE_URI = (
        f"mysql+pymysql://{DB_USER}:{DB_PASSWORD}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
    )
    
    # Disable modification tracking (not needed, improves performance)
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    
    # Secret key with production safety
    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"

How It Works

1. Loading Environment Variables

The load_dotenv() function reads your .env file and loads all variables into os.environ.

2. Constructing Database URI

SQLAlchemy requires a connection string in this format:

mysql+pymysql://username:password@host:port/database

The config builds this from individual environment variables.

3. Secret Key Safety

In production (FLASK_ENV=production), the app will crash if SECRET_KEY is not set. This prevents running production with insecure defaults.

4. Configuration Loading

The Flask app factory loads this configuration:

# app/__init__.py
def create_app():
    app = Flask(__name__)
    app.config.from_object(Config)  # Load Config class
    # ...

Database Setup

Install MySQL Server

Ensure MySQL is installed and running on your system:

Windows: MySQL Installer
macOS: brew install mysql or MySQL DMG
Linux: sudo apt-get install mysql-server (Ubuntu/Debian)

Start the MySQL service:

# macOS
brew services start mysql

# Linux
sudo systemctl start mysql

# Windows - MySQL runs as a service automatically

Create Database

Connect to MySQL and create the database:

mysql -u root -p

Enter your MySQL root password, then:

CREATE DATABASE muebles_roble_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Verify the database was created:

SHOW DATABASES;

Exit MySQL:

EXIT;

Create Database User (Optional)

For better security, create a dedicated user instead of using root:

CREATE USER 'muebles_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON muebles_roble_db.* TO 'muebles_user'@'localhost';
FLUSH PRIVILEGES;

Update your .env file:

DB_USER=muebles_user
DB_PASSWORD=secure_password

Test Database Connection

The application automatically tests the database connection when it starts. Run:

python run.py

You should see:

Database connection successful!

If you see an error, verify your database credentials in .env.

Database Connection String Examples

Here are example connection strings for different scenarios:

Local MySQL (Standard)

DB_USER=root
DB_PASSWORD=mypassword
DB_HOST=localhost
DB_PORT=3306
DB_NAME=muebles_roble_db

Results in:

mysql+pymysql://root:mypassword@localhost:3306/muebles_roble_db

Remote MySQL Server

DB_USER=admin
DB_PASSWORD=secure123
DB_HOST=192.168.1.100
DB_PORT=3306
DB_NAME=muebles_roble_db

Results in:

mysql+pymysql://admin:[email protected]:3306/muebles_roble_db

Custom Port

DB_USER=root
DB_PASSWORD=pass
DB_HOST=localhost
DB_PORT=3307
DB_NAME=muebles_roble_db

Results in:

mysql+pymysql://root:pass@localhost:3307/muebles_roble_db

Running Database Migrations

After configuring the database, you’ll need to create the tables:

Initialize Migrations

If migrations haven’t been initialized yet:

flask db init

This creates a migrations/ folder.

This step may already be done in the repository. Only run it if the migrations/ folder doesn’t exist.

Create Initial Migration

Generate a migration from your models:

flask db migrate -m "Initial tables"

This analyzes your models and creates migration scripts in migrations/versions/.

Apply Migrations

Apply the migration to create tables:

flask db upgrade

This executes the migration scripts and creates all tables in your database.

Verify Tables

Connect to MySQL and verify tables were created:

USE muebles_roble_db;
SHOW TABLES;

You should see tables like:

colors
wood_types
furniture_types
unit_of_measures
roles
alembic_version (migration tracking)

Environment-Specific Configuration

Development Environment

For local development, use these settings:

# .env
FLASK_APP=app.py
FLASK_ENV=development
FLASK_DEBUG=1

DB_USER=root
DB_PASSWORD=root
DB_HOST=localhost
DB_PORT=3306
DB_NAME=muebles_roble_dev

# Optional in development
SECRET_KEY=dev-secret-key

Development mode enables debug mode, auto-reloading, and detailed error pages.

Production Environment

For production deployment:

# .env
FLASK_APP=app.py
FLASK_ENV=production

DB_USER=production_user
DB_PASSWORD=very_secure_password_here
DB_HOST=db.example.com
DB_PORT=3306
DB_NAME=muebles_roble_prod

# REQUIRED in production
SECRET_KEY=generate_a_random_secure_key_here

Never commit your .env file to version control. The .gitignore file should include .env.

Troubleshooting Configuration Issues

Database connection fails

Error: Database connection failed: Access deniedSolutions:

Verify DB_USER and DB_PASSWORD are correct
Check that MySQL is running: mysql -u root -p
Ensure the user has permissions: SHOW GRANTS FOR 'user'@'localhost';
Verify the database exists: SHOW DATABASES;

Can't connect to MySQL server

Error: Can't connect to MySQL server on 'localhost'Solutions:

Check MySQL is running: systemctl status mysql (Linux) or brew services list (macOS)
Verify DB_HOST and DB_PORT are correct
Check firewall settings if connecting to a remote server
Try connecting manually: mysql -h localhost -P 3306 -u root -p

Environment variables not loading

Error: Variables are None or using defaultsSolutions:

Ensure .env file is in the project root (same directory as run.py)
Check file is named .env exactly (not .env.txt)
Verify python-dotenv is installed: pip list | grep dotenv
Add print statement to verify: print(os.getenv("DB_USER"))

SECRET_KEY error in production

Error: ValueError: SECRET_KEY must be set in production environmentSolutions:

Add SECRET_KEY to your .env file
Generate a secure key: python -c "import secrets; print(secrets.token_hex(32))"
Ensure FLASK_ENV=production is set correctly

Migration errors

Error: Target database is not up to dateSolutions:

Run migrations: flask db upgrade
Check migration status: flask db current
View migration history: flask db history
If needed, downgrade and reapply: flask db downgrade then flask db upgrade

Security Best Practices

Follow these security practices for production deployments:

Never commit .env files - Add .env to .gitignore
Use strong passwords - Generate random passwords for database users
Set SECRET_KEY - Use a cryptographically random string
Restrict database users - Grant only necessary permissions
Use environment variables - Never hard-code credentials
Enable SSL - Use encrypted database connections in production
Regular backups - Implement automated database backups

Verifying Configuration

You can verify your configuration is correct:

# test_config.py
from config import Config

print("Database URI:", Config.SQLALCHEMY_DATABASE_URI)
print("Secret Key Set:", bool(Config.SECRET_KEY))
print("Track Modifications:", Config.SQLALCHEMY_TRACK_MODIFICATIONS)

Run it:

python test_config.py

Don’t print the actual SECRET_KEY or passwords in production logs!

Next Steps

First Steps

Run the application and create your first catalog entries

Features

Learn about all available features and capabilities

Overview

Quickstart

Configuration Guide

Configuration Guide

Environment Variables Setup

Environment Variables Reference

Flask Variables

Database Variables

Configuration File Structure

How It Works

Database Setup

Database Connection String Examples

Local MySQL (Standard)

Remote MySQL Server

Custom Port

Running Database Migrations

Environment-Specific Configuration

Development Environment

Production Environment

Troubleshooting Configuration Issues

Security Best Practices

Verifying Configuration

Next Steps

First Steps

Features

Build docs developers (and LLMs) love

Overview

Quickstart

​Configuration Guide

​Environment Variables Setup

​Environment Variables Reference

​Flask Variables

​Database Variables

​Configuration File Structure

​How It Works

​Database Setup

​Database Connection String Examples

​Local MySQL (Standard)

​Remote MySQL Server

​Custom Port

​Running Database Migrations

​Environment-Specific Configuration

​Development Environment

​Production Environment

​Troubleshooting Configuration Issues

​Security Best Practices

​Verifying Configuration

​Next Steps

First Steps

Features

Build docs developers (and LLMs) love

Configuration Guide

Environment Variables Setup

Environment Variables Reference

Flask Variables

Database Variables

Configuration File Structure

How It Works

Database Setup

Database Connection String Examples

Local MySQL (Standard)

Remote MySQL Server

Custom Port

Running Database Migrations

Environment-Specific Configuration

Development Environment

Production Environment

Troubleshooting Configuration Issues

Security Best Practices

Verifying Configuration

Next Steps