|
| 1 | +# 🧠 BrainCheck |
| 2 | + |
| 3 | +A minimal Flask quiz application built **exclusively** to demonstrate DevOps concepts: Docker containerization, CI/CD with GitHub Actions, and automated testing. |
| 4 | + |
| 5 | +> **Note:** The application itself is intentionally simple. The focus is on deployment automation, not application features. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## 📋 Project Overview |
| 10 | + |
| 11 | +BrainCheck is a 5-question multiple-choice quiz app. No login, no database, no admin panel — just a clean demonstration of: |
| 12 | + |
| 13 | +- ✅ **Containerization** — Dockerfile & Docker Compose |
| 14 | +- ✅ **CI/CD Pipeline** — GitHub Actions (test → build → verify) |
| 15 | +- ✅ **Automated Testing** — pytest with 13 test cases |
| 16 | +- ✅ **One-Command Deployment** — `docker compose up` |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +## 🎯 Objectives |
| 21 | + |
| 22 | +| Objective | How It's Demonstrated | |
| 23 | +|---|---| |
| 24 | +| Automatic Deployment | `docker compose up` runs the entire app | |
| 25 | +| Deployment Automation | Dockerfile + docker-compose.yml handle everything | |
| 26 | +| CI/CD Pipeline | GitHub Actions runs tests and builds on every push | |
| 27 | +| Automated Testing | pytest validates routes, scoring, and health checks | |
| 28 | + |
| 29 | +--- |
| 30 | + |
| 31 | +## 🛠 Technology Stack |
| 32 | + |
| 33 | +| Technology | Version | Purpose | |
| 34 | +|---|---|---| |
| 35 | +| Python | 3.13 | Runtime | |
| 36 | +| Flask | 3.1.1 | Web framework | |
| 37 | +| pytest | 8.3.5 | Testing | |
| 38 | +| Docker | Latest | Containerization | |
| 39 | +| Docker Compose | Latest | Orchestration | |
| 40 | +| GitHub Actions | — | CI/CD | |
| 41 | + |
| 42 | +--- |
| 43 | + |
| 44 | +## 📁 Folder Structure |
| 45 | + |
| 46 | +``` |
| 47 | +BRAINCHECK/ |
| 48 | +├── app.py # Flask application (single file) |
| 49 | +├── requirements.txt # Python dependencies (2 packages) |
| 50 | +├── Dockerfile # Docker image definition |
| 51 | +├── docker-compose.yml # Docker Compose config |
| 52 | +├── .dockerignore # Docker build exclusions |
| 53 | +├── .gitignore # Git exclusions |
| 54 | +├── .env.example # Environment variable template |
| 55 | +├── README.md # This file |
| 56 | +├── templates/ |
| 57 | +│ ├── home.html # Landing page |
| 58 | +│ ├── quiz.html # Quiz page (5 MCQs) |
| 59 | +│ └── result.html # Score display |
| 60 | +├── static/ |
| 61 | +│ └── style.css # Stylesheet |
| 62 | +├── tests/ |
| 63 | +│ └── test_app.py # All automated tests |
| 64 | +└── .github/workflows/ |
| 65 | + └── ci.yml # GitHub Actions pipeline |
| 66 | +``` |
| 67 | + |
| 68 | +--- |
| 69 | + |
| 70 | +## 🚀 How to Run |
| 71 | + |
| 72 | +### Prerequisites |
| 73 | + |
| 74 | +- [Docker](https://docs.docker.com/get-docker/) installed on your machine |
| 75 | + |
| 76 | +### Quick Start |
| 77 | + |
| 78 | +```bash |
| 79 | +# Clone the repository |
| 80 | +git clone https://github.com/YOUR_USERNAME/BRAINCHECK.git |
| 81 | +cd BRAINCHECK |
| 82 | + |
| 83 | +# Run with Docker Compose (one command!) |
| 84 | +docker compose up --build |
| 85 | +``` |
| 86 | + |
| 87 | +Open [http://localhost:5000](http://localhost:5000) in your browser. |
| 88 | + |
| 89 | +### Stop the Application |
| 90 | + |
| 91 | +```bash |
| 92 | +docker compose down |
| 93 | +``` |
| 94 | + |
| 95 | +--- |
| 96 | + |
| 97 | +## 🐳 Docker Commands |
| 98 | + |
| 99 | +| Command | Description | |
| 100 | +|---|---| |
| 101 | +| `docker compose up --build` | Build and start the app | |
| 102 | +| `docker compose up -d` | Start in background (detached) | |
| 103 | +| `docker compose down` | Stop and remove containers | |
| 104 | +| `docker compose logs` | View application logs | |
| 105 | +| `docker compose ps` | Check container status | |
| 106 | +| `docker build -t braincheck .` | Build image manually | |
| 107 | +| `docker run -p 5000:5000 braincheck` | Run container manually | |
| 108 | + |
| 109 | +--- |
| 110 | + |
| 111 | +## ⚙️ GitHub Actions |
| 112 | + |
| 113 | +The CI/CD pipeline (`.github/workflows/ci.yml`) runs automatically on every push to `main`: |
| 114 | + |
| 115 | +### Pipeline Flow |
| 116 | + |
| 117 | +``` |
| 118 | +Push to main |
| 119 | + │ |
| 120 | + ▼ |
| 121 | +┌─────────────┐ ┌──────────────────┐ |
| 122 | +│ Run Tests │────▶│ Build Docker │ |
| 123 | +│ (pytest) │ │ Image & Verify │ |
| 124 | +└─────────────┘ └──────────────────┘ |
| 125 | +``` |
| 126 | + |
| 127 | +### What It Does |
| 128 | + |
| 129 | +1. **Checkout** — Clones the repository |
| 130 | +2. **Setup Python 3.13** — Installs the runtime |
| 131 | +3. **Install Dependencies** — `pip install -r requirements.txt` |
| 132 | +4. **Run pytest** — Executes all 13 tests |
| 133 | +5. **Build Docker Image** — `docker build -t braincheck:test .` |
| 134 | +6. **Verify Container** — Starts the container and hits `/health` |
| 135 | + |
| 136 | +--- |
| 137 | + |
| 138 | +## 🧪 Testing |
| 139 | + |
| 140 | +### Run Tests Locally |
| 141 | + |
| 142 | +```bash |
| 143 | +# Install dependencies |
| 144 | +pip install -r requirements.txt |
| 145 | + |
| 146 | +# Run all tests |
| 147 | +pytest tests/ -v |
| 148 | +``` |
| 149 | + |
| 150 | +### Test Coverage |
| 151 | + |
| 152 | +| Test | What It Verifies | |
| 153 | +|---|---| |
| 154 | +| `test_app_exists` | Flask app instance created | |
| 155 | +| `test_app_is_testing` | Test mode enabled | |
| 156 | +| `test_home_page_status` | Home page returns 200 | |
| 157 | +| `test_home_page_content` | Home page has "BrainCheck" | |
| 158 | +| `test_quiz_page_status` | Quiz page returns 200 | |
| 159 | +| `test_quiz_page_has_questions` | All 5 questions rendered | |
| 160 | +| `test_quiz_page_has_submit` | Submit button present | |
| 161 | +| `test_result_all_correct` | 5/5 = 100% | |
| 162 | +| `test_result_all_wrong` | 0/5 = 0% | |
| 163 | +| `test_result_partial_score` | 3/5 = 60% | |
| 164 | +| `test_result_no_answers` | Empty form = 0% | |
| 165 | +| `test_health_check` | `/health` returns healthy | |
| 166 | +| `test_questions_count` | Exactly 5 questions | |
| 167 | +| `test_questions_have_required_fields` | Data integrity check | |
| 168 | + |
| 169 | +--- |
| 170 | + |
| 171 | +## 🔮 Future Scope |
| 172 | + |
| 173 | +This project can be extended to demonstrate additional DevOps concepts: |
| 174 | + |
| 175 | +- **Multi-stage Docker builds** — Optimize image size |
| 176 | +- **Docker volumes** — Persist data with SQLite |
| 177 | +- **Environment-based configs** — Staging vs. production |
| 178 | +- **Nginx reverse proxy** — Multi-container setup |
| 179 | +- **Monitoring** — Prometheus + Grafana integration |
| 180 | +- **Container registry** — Push images to Docker Hub / GHCR |
| 181 | +- **Infrastructure as Code** — Terraform / Ansible integration |
| 182 | +- **Kubernetes** — Orchestration with K8s manifests |
| 183 | + |
| 184 | +--- |
| 185 | + |
| 186 | +## 📝 License |
| 187 | + |
| 188 | +This project is for educational purposes. |
| 189 | + |
| 190 | +--- |
| 191 | + |
| 192 | +<p align="center">Built with ❤️ to learn DevOps</p> |
0 commit comments