enferno

When writing backend logic, follow these established patterns to ensure consistency with the existing codebase:

Query Pattern (SQLAlchemy 2.x): Use db.select() for queries and db.paginate() for paginated results.

Response Pattern: API responses should return a dictionary containing the list of items (converted via .to_dict()) and the total count.

# Query pattern (SQLAlchemy 2.x)
query = db.select(User)
pagination = db.paginate(query, page=page, per_page=per_page)

# Response pattern
return {
    "items": [item.to_dict() for item in pagination.items],
    "total": pagination.total
}

To get a local development instance of Enferno running, clone the repository, run the setup script, initialize the database, and create an admin user.

Requirements:

• Python 3.11+
• uv

Steps:

1. Clone and enter the directory.
2. Run ./setup.sh to install dependencies and generate a secure .env file.
3. Initialize the database using uv run flask create-db.
4. Create your admin user with uv run flask install.
5. Start the server with uv run flask run.

The application will be available at http://localhost:5000.

git clone git@github.com:level09/enferno.git && cd enferno
./setup.sh                    # Installs deps + generates secure .env
uv run flask create-db        # Setup database
uv run flask install          # Create admin user
uv run flask run              # → http://localhost:5000

Enferno is a Flask framework designed for rapid deployment with zero build steps. It uses Vue 3 and Vuetify 3 directly in the browser, eliminating the need for npm, webpack, or vite. To get a project running immediately, use the provided setup script and the Flask CLI.

./setup.sh && flask run

For Ubuntu servers, the recommended way to deploy is using the enferno_cli tool. It automates server provisioning (supporting Python 3.13+), Nginx configuration with SSL, database setup (PostgreSQL/SQLite), Systemd service configuration, and security setup.

# Install the CLI tool
pip install enferno_cli

# Run the interactive setup
enferno setup

By default, Enferno uses SQLite. To enable asynchronous background tasks using Celery and Redis, you must install the full extra dependencies and configure your environment variables.

1. Run uv sync --extra full to install Redis and Celery support.
2. Configure REDIS_URL and CELERY_BROKER_URL in your .env file.

To run Enferno on your local machine, ensure you have Python 3.11+ and uv installed. Follow these steps to clone the repository, install dependencies, and initialize the application:

1. Install uv using pip or the official shell script.
2. Clone the repository and enter the directory.
3. Run ./setup.sh to install dependencies and generate a secure .env file.
4. Initialize the database using uv run flask create-db.
5. Create an admin user using uv run flask install.
6. Start the development server with uv run flask run.

The application will be available at http://localhost:5000.

# Install uv
pip install uv

# Clone and setup
git clone git@github.com:level09/enferno.git
cd enferno
./setup.sh
uv run flask create-db
uv run flask install
uv run flask run

When developing with Enferno, follow these security patterns:

1. Input Validation: Use Flask-WTF and WTForms to define forms with validators like DataRequired() and Length().
2. CSRF Protection: Ensure CSRFProtect(app) is initialized to prevent cross-site request forgery.
3. Authentication: Use the @auth_required() decorator from flask_security on routes that require a logged-in user.

from flask_wtf import FlaskForm
from wtforms import StringField
from wtforms.validators import DataRequired, Length

class PostForm(FlaskForm):
    title = StringField('Title', validators=[DataRequired(), Length(max=80)])

You can deploy Enferno to any Ubuntu VPS (e.g., Hetzner, DigitalOcean) using the ignite script. This handles Caddy (with auto SSL), Python 3.13, Redis, and systemd services.

Run the following command, replacing your-domain.com with your actual domain:

curl -sSL https://raw.githubusercontent.com/level09/ignite/main/ignite.sh | sudo DOMAIN=your-domain.com bash

Schema changes are managed via Flask-Migrate (Alembic).

Workflow for existing databases:

1. Draft a migration based on model changes:

   uv run flask db migrate -m "description"

2. Crucial: Review the generated file in migrations/versions/<revision>.py and adjust it if necessary.
3. Apply the migration:

   uv run flask db upgrade

Workflow for fresh databases:

• Use uv run flask create-db to build the full schema and stamp it automatically.

Legacy databases:

• If you are using a database created before migrations were implemented, run uv run flask db stamp head once before starting the standard migration workflow.

uv run flask db migrate -m "add status to user"
uv run flask db upgrade