Installation

This guide covers everything you need to install and configure the Soft-Bee API for development or production use.

System Requirements

Python

Version: 3.10 or higherRequired for running the Flask application

PostgreSQL

Version: 12 or higherPrimary database for all environments

pip

Version: LatestPython package manager

Installation Methods

Automated Setup (Recommended)
Manual Setup

Using the Initialization Script

The easiest way to get started is using the provided init_project.sh script:

Download the Script

Ensure you have the init_project.sh file in your project root:

ls -la init_project.sh
chmod +x init_project.sh

Run the Script

Execute the initialization script:

./init_project.sh

The script will:

Verify Python installation
Create project directory structure
Set up a virtual environment
Install base dependencies
Optionally install development dependencies

Respond to Prompts

When asked:

¿Instalar dependencias de desarrollo también? (s/n):

Type s or y for development setup (includes testing, linting tools)
Type n for minimal production setup

The script is designed for Linux/Mac. Windows users should follow the Manual Setup instructions below.

Step-by-Step Manual Installation

Verify Python Installation

Check that Python 3.10+ is installed:

python3 --version
# Should output: Python 3.10.x or higher

If not installed, download from python.org

Create Virtual Environment

Create an isolated Python environment:Linux/Mac:

python3 -m venv venv
source venv/bin/activate

Windows:

python -m venv venv
venv\Scripts\activate

Your prompt should now show (venv) prefix.

Upgrade pip

Ensure you have the latest pip version:

pip install --upgrade pip

Install Dependencies

Install based on your environment needs:

# Base + Production dependencies
pip install -r requirements/base.txt
pip install -r requirements/production.txt

Dependencies Overview

The project uses a modular requirements structure for different environments:

Base Dependencies (`requirements/base.txt`)

Core dependencies required for all environments:

Web Framework

Flask==3.1.1
Werkzeug==3.1.3
Flask-CORS==5.0.1
Flask-Login==0.6.3
Flask-Talisman==1.1.0

Flask and essential extensions for building the REST API.

Database & ORM

SQLAlchemy==2.0.41
Flask-SQLAlchemy==3.1.1
alembic==1.17.1
Flask-Migrate==4.0.5
psycopg2-binary==2.9.10

Database connectivity, ORM, and migration tools for PostgreSQL.

Security & Authentication

argon2-cffi==23.1.0
bcrypt==4.3.0
python-jose[cryptography]==3.3.0

Password hashing (Argon2, bcrypt) and JWT token handling.

Validation & Serialization

pydantic==2.11.5
email-validator==2.2.0

Request/response validation and email format checking.

Dependency Injection

dependency-injector==4.48.3

IoC container for Clean Architecture implementation.

Flask-Mail==0.10.0

Email sending functionality for verification and notifications.

Utilities

python-dotenv==1.1.0
requests==2.32.3
orjson==3.10.18
cachetools==5.5.2

Environment variables, HTTP client, fast JSON, and caching.

Development Dependencies (`requirements/development.txt`)

Additional tools for development:

pytest==8.3.4              # Testing framework
pytest-flask==1.3.0        # Flask testing utilities
Flask-DebugToolbar==0.14.1 # Debug toolbar for development
black==24.10.0             # Code formatter
mypy==1.14.0               # Static type checker

Database Setup

PostgreSQL Installation

macOS
Ubuntu/Debian
Windows
Docker

Using Homebrew:

brew install postgresql@14
brew services start postgresql@14

Using apt:

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Download the installer from postgresql.org
Run the installer and follow the setup wizard
Remember the password you set for the postgres user

Using Docker Compose:

docker-compose.yml

version: '3.8'
services:
  postgres:
    image: postgres:14
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: softbee_local
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Start the database:

docker-compose up -d

Create Database

Create the database for your environment:

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE softbee_local;

# Create user (optional)
CREATE USER softbee_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE softbee_local TO softbee_user;

# Exit
\q

For different environments, create separate databases:

softbee_local - Local development
softbee_dev - Development server
softbee_test - Testing
softbee_prod - Production

Environment Configuration

Create Environment File

Copy the example file and configure:

cp .env.example .env

Configuration Options

FLASK_ENV

string

default:"local"

Environment mode: local, development, production, or testing

SECRET_KEY

string

required

Flask secret key for session managementGenerate a secure key:

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

JWT_KEY

string

required

Secret key for JWT token signingGenerate a secure key:

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

DATABASE_URL

string

required

PostgreSQL connection stringFormat:

postgresql://username:password@host:port/database

Example:

postgresql://postgres:postgres@localhost:5432/softbee_local

ALGORITHM

string

default:"HS256"

JWT signing algorithm

EXPIRES_TOKEN_SESSION

integer

default:"1440"

Access token expiration in minutes (default: 24 hours)

EXPIRES_TOKEN_EMAIL

integer

default:"30"

Email verification token expiration in minutes

SMTP_HOST

string

SMTP server hostname (e.g., smtp.gmail.com)

SMTP_PORT

integer

default:"587"

SMTP server port

SMTP_USER

string

SMTP username/email for sending emails

SMTP_PASSWORD

string

SMTP password or app-specific password

FRONTEND_URL

string

default:"http://localhost:3000"

Frontend application URL for CORS and email links

BASE_URL

string

default:"http://localhost:5000"

Backend API base URL

Example Configuration

FLASK_ENV=local
SECRET_KEY=dev-secret-key-change-me
JWT_KEY=dev-jwt-key-change-me
ALGORITHM=HS256
EXPIRES_TOKEN_SESSION=1440
EXPIRES_TOKEN_EMAIL=30

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/softbee_local

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

FRONTEND_URL=http://localhost:3000
BASE_URL=http://localhost:5000

Never commit your .env file to version control! It contains sensitive credentials. The .gitignore file should already exclude it.

Database Migrations

Initialize Migrations

Set up Flask-Migrate for database versioning:

# Activate virtual environment
source venv/bin/activate  # Windows: venv\Scripts\activate

# Initialize migration directory (first time only)
flask db init

This creates a migrations/ directory to track database changes.

Create and Apply Migrations

Generate Migration

Create a migration script from model changes:

flask db migrate -m "Initial migration"

This analyzes your SQLAlchemy models and generates migration scripts.

Review Migration

Check the generated migration file in migrations/versions/:

ls migrations/versions/

Review the upgrade() and downgrade() functions to ensure correctness.

Apply Migration

Apply the migration to your database:

flask db upgrade

This executes the SQL commands to update your database schema.

Common Migration Commands

# Show current migration status
flask db current

# Show migration history
flask db history

# Upgrade to latest
flask db upgrade

# Upgrade to specific version
flask db upgrade <revision>

# Downgrade one version
flask db downgrade

# Downgrade to specific version
flask db downgrade <revision>

Verify Installation

Run the Application

Start the development server:

# Make sure virtual environment is activated
source venv/bin/activate

# Start Flask
flask run

You should see:

🚀 Iniciando aplicación en entorno: local
⚙️  Configuración activa: LocalConfig
📂 Usando base de datos: PostgreSQL
🔗 Servidor PostgreSQL: localhost:5432
🌐 URLs configuradas:
   Frontend: http://localhost:3000
   Backend: http://localhost:5000
🐛 Debug mode: True

==================================================
📋 Rutas registradas:
  {'POST', 'OPTIONS'} /api/v1/auth/login
  {'POST', 'OPTIONS'} /api/v1/auth/register
  {'GET', 'OPTIONS', 'HEAD'} /api/v1/auth/health
==================================================

 * Running on http://127.0.0.1:5000

Test the API

Verify the installation with a health check:

curl http://localhost:5000/api/v1/auth/health

Expected Response:

{
  "status": "healthy",
  "feature": "auth",
  "version": "1.0.0",
  "endpoints": [
    "/api/v1/auth/login",
    "/api/v1/auth/register",
    "/api/v1/auth/logout",
    "/api/v1/auth/verify"
  ]
}

If you see this response, your installation is successful!

Next Steps

Quickstart Guide

Make your first API calls and start building

Configuration

Learn about advanced configuration options

Development

Set up your development environment

Architecture

Understand the system architecture

Troubleshooting

Python version issues

If you get a Python version error:

# Check your Python version
python3 --version

# Use a specific Python version
python3.10 -m venv venv

# Or install Python 3.10+ from python.org

PostgreSQL connection failed

Common PostgreSQL connection issues:

PostgreSQL not running:

# Check status
sudo systemctl status postgresql  # Linux
brew services list                # macOS

# Start service
sudo systemctl start postgresql   # Linux
brew services start postgresql    # macOS

Wrong credentials:
- Verify username and password in .env
- Test connection: psql -U postgres -h localhost

Database doesn’t exist:

psql -U postgres
CREATE DATABASE softbee_local;

pip install fails

If dependency installation fails:

# Upgrade pip first
pip install --upgrade pip setuptools wheel

# Install with verbose output
pip install -r requirements/base.txt -v

# For psycopg2 issues on Mac:
brew install postgresql
pip install psycopg2-binary

# For psycopg2 issues on Linux:
sudo apt-get install libpq-dev python3-dev
pip install psycopg2-binary

Migration errors

If migrations fail:

# Remove migrations directory
rm -rf migrations/

# Reinitialize
flask db init
flask db migrate -m "Initial migration"
flask db upgrade

# If still failing, check:
# 1. Database exists and is accessible
# 2. DATABASE_URL in .env is correct
# 3. Models are imported in db.py

Virtual environment activation

Platform-specific activation:Linux/Mac (bash/zsh):

source venv/bin/activate

Linux/Mac (fish):

source venv/bin/activate.fish

Windows (CMD):

venv\Scripts\activate.bat

Windows (PowerShell):

venv\Scripts\Activate.ps1

If PowerShell blocks scripts:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Import errors

If you see module import errors:

# Ensure virtual environment is activated
which python  # Should point to venv/bin/python

# Reinstall dependencies
pip install -r requirements/base.txt

# Check if package is installed
pip list | grep flask

# Set PYTHONPATH if needed
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Getting Help

If you’re still experiencing issues:

GitHub Issues

Report bugs and request features on our GitHub repository

Documentation

Browse the full documentation for detailed guides

Get Started

Architecture

Configuration

System Requirements

Python

PostgreSQL

pip

Installation Methods

Using the Initialization Script

Step-by-Step Manual Installation

Dependencies Overview

Base Dependencies (`requirements/base.txt`)

Development Dependencies (`requirements/development.txt`)

Database Setup

PostgreSQL Installation

Create Database

Environment Configuration

Create Environment File

Configuration Options

Example Configuration

Database Migrations

Initialize Migrations

Create and Apply Migrations

Common Migration Commands

Verify Installation

Run the Application

Test the API

Next Steps

Quickstart Guide

Configuration

Development

Architecture

Troubleshooting

Getting Help

GitHub Issues

Documentation

Build docs developers (and LLMs) love

Get Started

Architecture

Configuration

​System Requirements

Python

PostgreSQL

pip

​Installation Methods

​Using the Initialization Script

​Step-by-Step Manual Installation

​Dependencies Overview

​Base Dependencies (requirements/base.txt)

​Development Dependencies (requirements/development.txt)

​Database Setup

​PostgreSQL Installation

​Create Database

​Environment Configuration

​Create Environment File

​Configuration Options

​Example Configuration

​Database Migrations

​Initialize Migrations

​Create and Apply Migrations

​Common Migration Commands

​Verify Installation

​Run the Application

​Test the API

​Next Steps

Quickstart Guide

Configuration

Development

Architecture

​Troubleshooting

​Getting Help

GitHub Issues

Documentation

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Using the Initialization Script

Step-by-Step Manual Installation

Dependencies Overview

Base Dependencies (`requirements/base.txt`)

Development Dependencies (`requirements/development.txt`)

Database Setup

PostgreSQL Installation

Create Database

Environment Configuration

Create Environment File

Configuration Options

Example Configuration

Database Migrations

Initialize Migrations

Create and Apply Migrations

Common Migration Commands

Verify Installation

Run the Application

Test the API

Next Steps

Troubleshooting

Getting Help