feat: Add automated development setup with pre-commit hooks and Ruff linting

.editorconfig

@@ -0,0 +1,52 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# Top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+indent_style = space
+indent_size = 4
+
+# Python files
+[*.py]
+indent_size = 4
+max_line_length = 88
+quote_type = "double"
+
+# YAML files
+[*.{yaml,yml}]
+indent_style = space
+indent_size = 2
+
+# JSON files
+[*.json]
+indent_style = space
+indent_size = 2
+
+# TOML files
+[*.toml]
+indent_style = space
+indent_size = 2
+
+# Markdown files
+[*.md]
+trim_trailing_whitespace = false
+
+# Makefiles
+[Makefile]
+indent_style = tab
+
+# Dockerfiles
+[Dockerfile]
+indent_style = space
+indent_size = 4
+
+# Shell scripts
+[*.sh]
+indent_style = space
+indent_size = 2

.pre-commit-config.yaml

@@ -11,6 +11,20 @@ repos:
         exclude: ^app/alembic/
       - id: check-added-large-files
         exclude: ^app/alembic/
+      - id: check-toml
+        exclude: ^app/alembic/
+      - id: check-yaml
+        exclude: ^app/alembic/
+        types_or: [yaml, yml]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.1
+    hooks:
+      - id: ruff
+        args: [--fix, --show-fixes]
+        exclude: ^app/alembic/
+      - id: ruff-format
+        exclude: ^app/alembic/
 
   - repo: https://github.com/myint/autoflake
     rev: v2.3.1

.vscode/settings.json

@@ -0,0 +1,27 @@
+{
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.ruff": "explicit",
+    "source.organizeImports.ruff": "explicit"
+  },
+  "editor.defaultFormatter": "charliermarsh.ruff",
+  "editor.rulers": [88],
+  "python.analysis.typeCheckingMode": "basic",
+  "python.linting.enabled": true,
+  "python.linting.ruffEnabled": true,
+  "python.linting.pylintEnabled": false,
+  "python.formatting.provider": "none",
+  "python.analysis.autoImportCompletions": true,
+  "python.analysis.autoSearchPaths": true,
+  "python.analysis.diagnosticMode": "workspace",
+  "python.analysis.inlayHints.variableTypes": true,
+  "python.analysis.inlayHints.functionReturnTypes": true,
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.ruff": "explicit",
+      "source.organizeImports.ruff": "explicit"
+    }
+  }
+}

README.md

@@ -17,109 +17,136 @@ This is a template project for a FastAPI application with a PostgreSQL database,
   - Password reset functionality
 - **Environment-based configuration**: Different settings for development, staging, and production
 
-## Prerequisites
+## Getting Started
 
-- **Local Development**:
-  - Python 3.11 or higher
-  - PostgreSQL installed locally or accessible
-  - pip or another Python package manager
+### Prerequisites
 
-- **Docker Deployment**:
-  - Docker and Docker Compose installed
-  - A code editor (e.g., VS Code)
-  - A terminal or command prompt
+- **Python 3.11+** and pip/uv
+- **PostgreSQL** (local or remote)
+- **Git** for version control
+- **Docker & Docker Compose** (for containerized development)
+- **Terminal/Command Prompt** (PowerShell recommended for Windows)
 
-## Basic Configuration
+### Quick Start
 
-1.  **Environment Variables**:
-    This project uses a `.env` file for local development configuration. If it doesn't exist, run this command to create:
+**Clone the repository**:
+   ```bash
+   git clone https://github.com/Texagon-Dev/fastapi-postgres-template your-project-name
+   cd your-project-name
+   git remote set-url origin <your-project-repo-url>
+   ```
 
-    ```python
-    cp .env.example .env
-    ```
+### Development Setup
 
-    Ensure you set the following environment variables in your `.env` file:
+### Option 1: Automated Setup (Recommended)
+We provide a setup script to help you get started quickly. Choose the appropriate command for your operating system:
 
-```python
-# Core settings
-FRONTEND_URL='http://localhost:3000'
-SECRET_KEY='your_32_char_strong_secret_key_here'
-DEBUG=True
-ENVIRONMENT='development'  # Options: development, staging, production
-
-# Database settings
-POSTGRES_USER="your_username"
-POSTGRES_PASSWORD="your_password"
-POSTGRES_DB_NAME="fastapi_db"
-
-# Authentication
-ALGORITHM='HS256'
-ACCESS_TOKEN_EXPIRE_MINUTES=30  # Short-lived access tokens for security
-REFRESH_TOKEN_EXPIRE_DAYS=7     # Longer-lived refresh tokens
+#### Mac/Linux:
+```bash
+# Make the script executable
+chmod +x scripts/dev_setup.py
+
+# Run the setup script
+./scripts/dev_setup.py
 ```
 
-## Local Installation and Setup
+#### Windows (Command Prompt):
+```cmd
+# Run the setup script directly with Python
+python scripts/dev_setup.py
+```
 
-#### (Recommended uv)
+#### Windows (PowerShell):
+```powershell
+# Run the setup script directly with Python
+python .\scripts\dev_setup.py
+```
 
-1. **Install dependencies directly with uv**:
+### Option 2: Manual Setup
+**The setup script will**:
+- Create a `.env` file from the example
+- Set up git hooks
+- Install pre-commit hooks
+
+    2. **Set up environment**:
+   - Copy the example environment file:
+     ```bash
+     # Linux/macOS
+     cp .example.env .env
+
+     # Windows (Command Prompt)
+     copy .example.env .env
+
+     # Windows (PowerShell)
+     Copy-Item -Path .example.env -Destination .env
+     ```
+   - Update the `.env` file with your configuration (see Configuration section below)
+
+    ### Configuration
+
+    - Edit the `.env` file with your settings:
+
+    ```env
+    # Core settings
+    FRONTEND_URL='http://localhost:3000'
+    SECRET_KEY='your_32_char_strong_secret_key_here'
+    DEBUG=True
+    ENVIRONMENT='development'  # Options: development, staging, production
+
+    # Database settings
+    POSTGRES_USER="your_username"
+    POSTGRES_PASSWORD="your_password"
+    POSTGRES_DB_NAME="fastapi_db"
+
+    # Authentication
+    ALGORITHM='HS256'
+    ACCESS_TOKEN_EXPIRE_MINUTES=30  # Short-lived access tokens for security
+    REFRESH_TOKEN_EXPIRE_DAYS=7     # Longer-lived refresh tokens
+    ```
 
+    3. **Install dependencies** (using uv - recommended):
    ```bash
-   # uv will make .venv automatically
+   # Install dependencies and create virtual environment
    uv sync
+
+   # Activate virtual environment
+   # Linux/macOS:
+   source .venv/bin/activate
+   # Windows (Command Prompt):
+   .venv\Scripts\activate
+   # Windows (PowerShell):
+   .\.venv\Scripts\Activate.ps1
    ```
-2. **Install new dependencies with uv**:
 
+    4. **Set up the database**:
    ```bash
-   uv add dependency_name
-   ```
-3. **Run server**:
-
-   ```bash
-   uv run uvicorn app.main:app --reload
-   ```
-   OR if you have make available
-   ```
-   make start
-   ```
-
-#### (Not recommended)
-
-1. **Create a virtual environment**:
-
-   ```bash
-   # Using standard venv
-   python -m venv venv
-   source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-   # OR using uv (faster)
-   uv venv
-   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   # Run migrations
+   uv run alembic upgrade head
+
+   # Or using make (if available)
+   make alembic-upgrade
    ```
 
-2. **Install dependencies**:
-
+   5. **Set up pre-commit hooks**:
    ```bash
-   # Using pip
-   pip install -r requirements.txt
-
-   # OR using uv (faster)
-   uv pip install -r requirements.txt
+   # Linux/macOS/Windows (Git Bash)
+   cp misc/pre-commit .git/hooks/pre-commit
+   chmod +x .git/hooks/pre-commit
+
+   # Windows (Command Prompt)
+   copy /Y misc\pre-commit .git\hooks\pre-commit
    ```
 
+    6. **Start the development server**:
+    ```bash
+    # Using uvicorn directly
+    uv run uvicorn app.main:app --reload
+
+    # Or using make (if available)
+    make start
+    ```
+    The API will be available at `http://localhost:8000` and interactive docs at `http://localhost:8000/docs`
 
-#### Set up the database:
-
-   Create your PostgreSQL database and run migrations:
-
-   ```bash
-   # Make sure you've set the correct DATABASE_URL in your .env file
-   alembic upgrade head
-   ```
-   OR if you have make available
-   ```
-   make alembic-upgrade
-   ```
 
 ### Database Migrations Guide
 

misc/pre-commit

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Get list of staged Python files
+files=$(git diff --cached --name-only --diff-filter=ACM | grep "\\.py$")
+
+echo "Modified Python files: $files"
+
+# If no Python files are modified, exit successfully
+if [ -z "$files" ]; then
+    echo "No Python files modified. Skipping pre-commit hooks."
+    exit 0
+fi
+
+# Run ruff on the modified files with --output-format=full to capture warnings
+echo "🔍 Running ruff checks..."
+# Capture both stdout and stderr to catch warnings
+ruff_output=$(uv run ruff check $files --output-format=full 2>&1)
+ruff_exit_code=$?
+
+# Check if there are any warnings or errors
+if [[ $ruff_output == *"warning:"* ]] || [ $ruff_exit_code -ne 0 ]; then
+    echo "❌ Ruff found issues that need to be fixed:"
+    echo "$ruff_output"
+    echo "\nPlease fix the above issues before committing."
+    exit 1
+fi
+
+# Capture the exit code of the pre-commit command
+pre_commit_exit_code=$?
+
+# If pre-commit found issues, exit with its exit code
+if [ $pre_commit_exit_code -ne 0 ]; then
+    echo "❌ Pre-commit hooks found issues that need to be fixed"
+    exit $pre_commit_exit_code
+fi
+
+echo "✅ All checks passed"
+exit 0