The init command creates a complete Framefox project structure with all necessary files and directories.
Usage
What It Does
The init command performs the following actions:
- System Requirements Check - Validates that your system meets the minimum requirements
- Directory Creation - Creates the project directory structure
- File Generation - Generates all required configuration and template files
- Secret Key Generation - Creates a secure session secret key
System Requirements
Before initializing, the command checks:
- Python Version - Python 3.12 or higher
- Operating System - Windows, Linux, or macOS
- Permissions - Write access to home directory
- Disk Space - Minimum 100 MB available
Example Output
$ framefox init
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Component ┃ Status ┃ Required ┃ Current ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ Python Version │ OK │ Python 3.12+ │ Python 3.12.0 │
│ Operating System │ OK │ Win/Linux/MacOS │ Linux │
│ User Permissions │ OK │ Write in home │ OK │
│ Disk Space │ OK │ 100 MB minimum │ 50000 MB │
└─────────────────────┴────────────┴─────────────────┴────────────────┘
✓ Your system is compatible with Framefox
✓ Project created successfully
Next, try framefox to see the available commands
Project Structure
The command creates the following structure:
.
├── config/ # Configuration files
│ ├── application.yaml # Application settings
│ ├── orm.yaml # Database ORM configuration
│ ├── security.yaml # Security settings
│ ├── mail.yaml # Email configuration
│ ├── debug.yaml # Debug settings
│ ├── parameter.yaml # Custom parameters
│ ├── services.yaml # Service definitions
│ └── tasks.yaml # Task configuration
├── migrations/ # Database migrations
│ ├── versions/ # Migration version files
│ ├── env.py # Migration environment
│ └── script.py.mako # Migration template
├── public/ # Static assets
├── src/ # Application source code
│ ├── controller/ # Controllers
│ ├── entity/ # Entities
│ ├── repository/ # Repositories
│ ├── security/ # Security components
│ └── tests/ # Unit tests
├── templates/ # HTML templates
│ └── base.html # Base template
├── var/ # Runtime files
│ ├── cache/ # Cache files
│ ├── log/ # Log files
│ └── session/ # Session data
├── .env # Environment variables
├── .gitignore # Git ignore rules
├── main.py # Application entry point
└── requirements.txt # Python dependencies
Generated Files
Configuration Files
All YAML configuration files are created with sensible defaults:
- application.yaml - Application name, environment, debug mode
- orm.yaml - Database connection settings
- security.yaml - Authentication and authorization
- mail.yaml - Email server configuration
Environment File
The .env file contains:
APP_ENV=dev
APP_DEBUG=True
DATABASE_URL=sqlite:///./framefox.db
SESSION_SECRET_KEY=<generated-secret>
Main Entry Point
The main.py file contains the application startup code.
Handling Existing Files
If files or directories already exist, the command will:
- List all existing items that would be overwritten
- Prompt you to choose:
- Cancel - Abort the initialization
- Overwrite - Replace existing files
The following files/directories already exist:
• src/ (directory)
• main.py (file)
• .env (file)
What do you want to do?
1. Cancel initialization
2. Overwrite existing files/directories
Your choice:
The var/ directory is always overwritten without prompting to ensure a clean state for cache, logs, and sessions.
Next Steps
After initialization:
-
Install Dependencies
pip install -r requirements.txt
-
Review Configuration
-
Create the Database
-
Start Development Server
Tips
- Always run
init in an empty directory or a directory you’re willing to overwrite
- The generated secret key in
.env is cryptographically secure
- Keep your
.env file out of version control (it’s in .gitignore by default)
Troubleshooting
Permission Denied
If you encounter permission errors:
sudo chown -R $USER:$USER .
Python Version Mismatch
Ensure you’re using Python 3.12 or higher:
Disk Space Issues
Check available disk space: