Installation and Configuration

Prerequisites

Before installing Framefox, make sure you have:

Python 3.12+

Latest Python version installed on your system

Python package manager

pip or uv installed

Code Editor

VS Code, Vim, or your preferred editor

Installation

1. Install Framefox via pip

   The simplest way to install Framefox:

   pip install framefox

2. Installation in a virtual environment (recommended)

   # Create a virtual environment
   python -m venv venv
   
   # Activate the virtual environment
   # On Linux/macOS:
   source venv/bin/activate
   # On Windows:
   venv\Scripts\activate
   
   # Install Framefox
   pip install framefox

3. Installation with uv (faster)

   If you have uv installed, you can use it for faster installation:

   # In a virtual environment
   uv init
   source .venv/bin/activate  # Linux/macOS
   # .venv\Scripts\activate   # Windows
   uv add framefox

Create a new project

1. Create the project folder

   mkdir my-project
   cd my-project

2. Initialize the Framefox project

   framefox init

3. Explore the generated structure

   This command will automatically create the basic structure:

   • Directorymy-project/

     • Directorysrc/

       • Directorycontrollers/ User application controllers

         • …
       • Directoryentity/ Database entities (models)

         • …
       • Directoryrepository/ Custom repository classes

         • …
     • Directoryconfig/ Application configuration

       • application.yaml Main application configuration
       • debug.yaml Debug configuration
       • mail.yaml Email configuration
       • orm.yaml ORM configuration
       • parameter.yaml Application parameters
       • security.yaml Security configuration
       • services.yaml Services configuration
       • tasks.yaml Tasks configuration
     • Directorypublic/ Static assets

       • …
     • Directorymigrations/ Database migrations

       • …
     • Directorytemplates/ Jinja2 templates

       • …
     • Directoryvar/ Variable data (logs, cache)

       • …
     • .env Environment variables
     • requirements.txt Python dependencies
     • main.py Application entry point

Configuration

Application configuration

config/application.yaml

application:
  env: "${APP_ENV}"
  template_dir: "templates"
  openapi_url: /openapi.json #empty value to disable openapi swagger ui
  redoc_url: /redoc

  controllers:
    dir: "src/controllers/"
  profiler:
    enabled: true # Set to false in production
  cors:
    allow_origins:
      - "http://localhost"
      - "http://localhost:8000"
    allow_credentials: true
    allow_methods:
      - "*"
    allow_headers:
      - "*"

  session:
    name: "session_id"
    file_path: var/session/sessions.db
    secret_key: "${SESSION_SECRET_KEY}"

  cookie:
    max_age: 3600 # 1 hour
    secure: true
    http_only: true
    same_site: "strict" # "strict", "lax", "none"
    path: "/"

Runtime Settings

env: Runtime environment (dev, prod, test)
template_dir: Jinja2 templates directory
openapi_url / redoc_url: URLs for automatic API documentation

Performance

profiler.enabled: Enable/disable performance profiler
cors: CORS configuration for APIs
controllers.dir: Application controllers directory

Security

session: User session management parameters
cookie: Security cookie configuration
secret_key: Session encryption key

ORM Configuration

config/services.yaml

database:
  # You can use either the URL format or the detailed configuration
  # If both are provided, DATABASE_URL environment variable takes precedence,
  # followed by the url field here, and finally the detailed configuration.

  # Option 1: Database URL
  url: "${DATABASE_URL}"

  # Option 2: Detailed configuration (useful for Docker/Kubernetes)
  # Uncomment and adjust these settings if needed, they will be used
  # only if no url is specified above or in environment variables
  # driver: "${DATABASE_DRIVER:-postgresql}"
  # host: "${DATABASE_HOST:-localhost}"
  # port: "${DATABASE_PORT:-5432}"
  # username: "${DATABASE_USER:-framefox}"
  # password: "${DATABASE_PASSWORD}"
  # database: "${DATABASE_NAME:-framefoxdb}"
  # charset: "utf8mb4"

  # Connection pooling settings (important for production)
  pool_size: 20
  max_overflow: 10
  pool_timeout: 30
  pool_recycle: 1800
  pool_pre_ping: true
  autocommit: false
  autoflush: false

Connection

url: Database connection URL
pool_size: Number of connections in the pool
max_overflow: Additional connections allowed

Performance

pool_timeout: Timeout to obtain a connection
pool_recycle: Connection lifetime (seconds)
pool_pre_ping: Connection verification before use

Transaction Management

autocommit/autoflush: Automatic transaction management
Recommended to keep false for better control

Environment Variables Setup

1. Configure your .env file

   .env

   #==============================
   # App environment
   #==============================
   
   APP_ENV=dev # can be dev or prod
   SESSION_SECRET_KEY=your-very-secret-key
   
   #==============================
   # Database
   #==============================
   
   # uncomment the line you want below, to use the database you want
   DATABASE_URL=sqlite:///app.db
   # DATABASE_URL=postgresql://root:password@localhost:5432/dbname
   # DATABASE_URL=mysql://root:password@localhost:3306/dbname
   
   #==============================
   # Mail
   #==============================
   # MAIL_URL=smtp://username:password@host:port?tls=true
   
   #==============================
   # Task transport
   #==============================
   # RABBITMQ_URL=amqp://guest:guest@localhost:5672/%2F

2. Choose your database

   For MySQL:

   DATABASE_URL=mysql://root:password@localhost:3306/dbname

   For PostgreSQL:

   DATABASE_URL=postgresql://root:password@localhost:5432/dbname

   For SQLite (default):

   DATABASE_URL=sqlite:///app.db

Additional Configuration Files

Debug Configuration

config/debug.yaml - Profiler settings, logging configuration, retention policies

Email Configuration

config/mail.yaml - SMTP settings, templates directory, queue configuration

Security Configuration

config/security.yaml - Authentication providers, firewalls, access control rules

Services Configuration

config/services.yaml - Dependency injection, service autowiring

Tasks Configuration

config/tasks.yaml - Background tasks, worker settings, queue management

Parameters Configuration

config/parameter.yaml - Custom application parameters and variables

Installation Verification

1. Start the development server

   framefox run

2. Check the output

   You should see something like:

   Starting the server on port 8000
   INFO:     Will watch for changes in these directories: ['/my_project']
   INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
   INFO:     Started reloader process [16768] using StatReload

3. Visit your application

   Open http://localhost:8000 in your browser. You should see the default Framefox homepage! 🎉

Useful Commands

Once your project is configured, here are the main commands:

Development Server

# Start the development server
framefox run

# Start without auto-opening browser
framefox run --no-browser

Code Generation

# Create an entity
framefox create entity

# Create a controller
framefox create controller

Database Management

# Create database
framefox database create

# Create migration
framefox database create-migration

# Apply migrations
framefox database upgrade

Debugging

# List all routes
framefox debug router

# Clear cache
framefox cache clear

Ready to build something?

Now that Framefox is installed, here’s what you can do next:

1. How do I handle web requests? - Create your first controller
2. How do I store and manage data? - Set up your database
3. How do I organize my URLs? - Define URL patterns and app structure