FlaskAppEnhanced

Small Flask app scaffold with basic security features, tests, and CI.

This repository is also set up as a GitHub learning example: you can use it to understand common repo files, workflows, and where to click in GitHub.

Quick links:

• App docs and setup: README.md
• GitHub walkthrough: docs/GITHUB_GUIDE.md
• Contributing workflow: CONTRIBUTING.md
• Security reporting: SECURITY.md

Table of Contents

• Features
• Quick Start (Local)
• Run as an Installed Package
• Run with Docker
• Development Commands
• Project Structure
• Environment
• Production Run (Example)
• Deploy a Live Demo
• Troubleshooting
• Learning Path
• First 10 Minutes (Beginner Click Guide)
• Sharing for Learning
• Public Launch Checklist
• Analytics and Privacy
• Learn GitHub Using This Repo
• GitHub Page Anatomy (Quick Reference)
• Security Notes

Features

• Homepage at /
• Health check at /health
• CSRF-protected form at /submit
• JSON API example at /api/echo
• Rate limiting via Flask-Limiter
• Security headers and request IDs
• GitHub Actions CI (.github/workflows/ci.yml)
• GitHub Release automation (.github/workflows/release.yml)
• GitHub Container Registry package workflow (.github/workflows/package.yml)

Quick Start (Local)

python -m venv venv
.\venv\Scripts\activate
pip install -r requirements.txt
python app.py

Visit:

• http://127.0.0.1:5000/
• http://127.0.0.1:5000/health

Quick test after startup:

curl http://127.0.0.1:5000/health

Run as an Installed Package

You can also install and run this as a Python package:

pip install .
flaskappenhanced

Alternative:

python -m app

Run with Docker

Build and run locally with Docker:

docker build -t flaskappenhanced:local .
docker run --rm -p 8000:8000 -e SECRET_KEY=change-me flaskappenhanced:local

Then visit:

• http://127.0.0.1:8000/
• http://127.0.0.1:8000/health

This repo also publishes a container image to GitHub Container Registry (GHCR) via .github/workflows/package.yml.

Example GHCR image (replace tag as needed):

docker pull ghcr.io/dkupratis-debug/flaskappenhanced:latest
docker run --rm -p 8000:8000 -e SECRET_KEY=change-me ghcr.io/dkupratis-debug/flaskappenhanced:latest

Development Commands

pip install -r requirements-dev.txt
ruff check .
pytest

One-line local package build check:

python -m build

Task runners:

• Makefile for Unix/macOS (make test, make lint, etc.)
• tasks.ps1 for PowerShell (.\tasks.ps1 test, .\tasks.ps1 lint, etc.)

Project Structure

• app/ - Flask app package, routes, templates, static files
• tests/ - Pytest test suite
• .github/workflows/ - CI and release automation
• docs/ - GitHub UI and contributor learning docs
• config.py - Environment-based config classes
• requirements*.txt - Runtime and development dependencies
• pyproject.toml - Project metadata, tooling, packaging configuration

Environment

Copy .env.example to .env and update values as needed. python-dotenv loads .env automatically if installed.

Useful variables:

• FLASK_ENV=development|production
• SECRET_KEY=...
• RATELIMIT_DEFAULT=200 per day;50 per hour
• RATELIMIT_STORAGE_URI=memory:// (use Redis in production)
• LOG_FILE=logs/app.log

Production Run (Example)

pip install -r requirements.txt
$env:FLASK_ENV="production"
$env:SECRET_KEY="change-me"
gunicorn -c gunicorn.conf.py wsgi:app

Deploy a Live Demo

This repository includes a starter Render blueprint in render.yaml so you can create a real demo URL and add it to GitHub About -> Website.

Start here:

• docs/DEPLOY_DEMO.md (deployment steps and safety notes)
• render.yaml (starter configuration)

Troubleshooting

GitHub shows an older commit

GitHub only shows new code after git add + git commit + git push.

GitHub shows a different account on the commit

Commit attribution comes from your local git user.name / user.email, not just the repo owner.

pytest warnings about cache permissions

This repo disables pytest's cache provider in pyproject.toml to avoid noisy permission warnings in restricted environments.

Rate limiting in production

memory:// works for local demos, but use Redis in production (RATELIMIT_STORAGE_URI) for accurate limits across processes.

Releases vs Packages on GitHub

• Releases in this repo contains versioned source/wheel artifacts (for example v0.2.0)
• Packages is for registry-published packages (this repo publishes a container image to GHCR via Actions)

Learning Path

Use this repo as a hands-on GitHub + Flask lab.

Beginner path (60-90 minutes)

1. Read README.md and docs/GITHUB_GUIDE.md
2. Run the app locally and open /health
3. Run pytest and ruff check .
4. Create a branch and make a tiny README change
5. Push branch and open a PR
6. Watch the CI run in GitHub Actions
7. Merge the PR (if allowed in your fork)
8. Inspect the commit history, release page, and package workflow
9. (Optional) Deploy a demo app and add the URL to the repo About section

Reviewer path

1. Open a PR
2. Use docs/PR_REVIEW_CHECKLIST.md
3. Review code, tests, config, docs, and security impact
4. Check CI and release/package workflows

First 10 Minutes (Beginner Click Guide)

If you are brand new to GitHub, start with:

• docs/FIRST_10_MINUTES.md

This is a click-by-click walkthrough that shows exactly where to go first:

• repo homepage / README
• pinned Start Here issue
• workshop issues
• Actions
• Releases
• Packages

Sharing for Learning

To share this repo with learners effectively:

1. Send the repo link plus a short goal:
   • "Learn GitHub PRs, Actions, Releases, and Packages using a small Flask app."
2. Tell learners where to start:
   • README.md
   • docs/GITHUB_GUIDE.md
   • CONTRIBUTING.md
3. Give them a first task:
   • "Change a README line and open a PR"
4. Ask them to inspect:
   • Actions tab
   • Releases tab
   • Packages section
5. Use forks for practice so they can safely merge in their own copy

Read docs/SAFE_SHARING.md before posting publicly (especially on social media).

Public Launch Checklist

Before making this repo public or sharing it widely, use:

• docs/PUBLIC_LAUNCH_CHECKLIST.md
• docs/SAFE_SHARING.md

These docs explain how to share safely while keeping your repo protected.

Analytics and Privacy

If you want to understand how people use the repo or demo app, start with:

• docs/ANALYTICS_AND_PRIVACY.md

Short version:

• Use GitHub Insights -> Traffic for repo-level traffic (views/clones/referrers)
• Use app logs for demo usage patterns
• Prefer aggregate, privacy-first analytics over invasive user tracking

Learn GitHub Using This Repo

Start here:

• README.md (project overview)
• docs/FIRST_10_MINUTES.md (fast beginner click guide)
• CONTRIBUTING.md (branching, commit, PR flow)
• docs/GITHUB_GUIDE.md (GitHub UI walkthrough)
• docs/PR_REVIEW_CHECKLIST.md (how to review PRs)
• docs/ARCHITECTURE.md (request flow and components)
• docs/VERSIONING_AND_RELEASES.md (version/tag/release flow)
• docs/SAFE_SHARING.md (how to share safely)
• docs/PUBLIC_LAUNCH_CHECKLIST.md (how to prepare for public sharing)
• docs/ANALYTICS_AND_PRIVACY.md (tracking usage ethically)
• docs/DEPLOY_DEMO.md (how to get a live demo URL)
• docs/exercises/CODEOWNERS_REVIEW_EXERCISE.md (guided practice PR)
• .github/workflows/ci.yml (automation)
• .github/PULL_REQUEST_TEMPLATE.md (PR structure)
• .github/ISSUE_TEMPLATE/ (issue forms)
• SECURITY.md (security policy)

GitHub Setup Status (Example Repo)

This repository is configured as a practical GitHub example and includes:

• About section with description, homepage, and topics
• Branch protection on main (PR review + required CI + admin enforcement)
• CI, Release, and GHCR package workflows
• Dependabot alerts and automated security fixes
• Issue/PR templates, CODEOWNERS, CONTRIBUTING.md, and SECURITY.md
• CODE_OF_CONDUCT.md and SUPPORT.md

Visual Walkthrough Assets

Screenshot/GIF placeholders and capture plan live in:

• docs/images/README.md
• docs/images/CAPTURE_CHECKLIST.md

Add screenshots there to make the GitHub guide more visual for friends and learners.

Maintainer Workflow (Current)

Because main is protected (including admins), changes should go through:

1. Create a branch
2. Push branch
3. Open PR
4. Wait for CI
5. Merge PR

GitHub Page Anatomy (Quick Reference)

When you open this repository on GitHub, you will usually see:

• README
  • Project overview and setup instructions (README.md)
• Security policy
  • Vulnerability reporting guidance (SECURITY.md)
• Activity
  • Recent repository changes and maintenance signals
• Stars
  • How many users bookmarked/liked the repo
• Watchers
  • How many users are subscribed to repo notifications
• Forks
  • How many copies of the repo exist in other accounts (often used for contributions)

These counts (Stars, Watchers, Forks) are GitHub UI stats and update automatically over time.

Security Notes

• CSRF enabled for HTML form submissions (Flask-WTF)
• /api/echo is CSRF-exempt intentionally as a demo JSON endpoint
• Request IDs are added to logs and responses via X-Request-Id
• Rate-limit storage should be Redis in production for accuracy