Skip to content

Commit 974bc4e

Browse files
Complete BrainCheck - DevOps demo with Flask, Docker, CI/CD, and automated testing
0 parents  commit 974bc4e

14 files changed

Lines changed: 854 additions & 0 deletions

File tree

‎.dockerignore‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
__pycache__
2+
*.pyc
3+
*.pyo
4+
.git
5+
.gitignore
6+
.env
7+
.env.example
8+
README.md
9+
tests/
10+
.github/
11+
*.md
12+
.pytest_cache

‎.env.example‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# BrainCheck Environment Variables
2+
# Copy this file to .env and update values as needed.
3+
4+
SECRET_KEY=change-me-to-a-random-string
5+
FLASK_DEBUG=0
6+
PORT=5000

‎.github/workflows/ci.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: CI — Build & Test
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
name: Run Tests
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
# 1. Checkout repository
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
19+
# 2. Setup Python
20+
- name: Setup Python 3.13
21+
uses: actions/setup-python@v5
22+
with:
23+
python-version: "3.13"
24+
25+
# 3. Install dependencies
26+
- name: Install dependencies
27+
run: pip install -r requirements.txt
28+
29+
# 4. Run tests
30+
- name: Run pytest
31+
run: pytest tests/ -v
32+
33+
docker:
34+
name: Build Docker Image
35+
runs-on: ubuntu-latest
36+
needs: test
37+
38+
steps:
39+
# 1. Checkout repository
40+
- name: Checkout code
41+
uses: actions/checkout@v4
42+
43+
# 2. Build Docker image
44+
- name: Build Docker image
45+
run: docker build -t braincheck:test .
46+
47+
# 3. Verify container starts
48+
- name: Start container and verify
49+
run: |
50+
docker run -d --name braincheck-test -p 5000:5000 braincheck:test
51+
sleep 5
52+
curl --fail http://localhost:5000/health || exit 1
53+
docker stop braincheck-test
54+
docker rm braincheck-test

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
__pycache__/
2+
*.pyc
3+
*.pyo
4+
.env
5+
*.db
6+
.pytest_cache/
7+
instance/
8+
.venv/
9+
venv/

‎Dockerfile‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# ---- Build Stage ----
2+
FROM python:3.13-slim
3+
4+
# Prevent Python from writing .pyc files and enable unbuffered output
5+
ENV PYTHONDONTWRITEBYTECODE=1
6+
ENV PYTHONUNBUFFERED=1
7+
8+
# Set working directory
9+
WORKDIR /app
10+
11+
# Install dependencies first (leverages Docker layer caching)
12+
COPY requirements.txt .
13+
RUN pip install --no-cache-dir -r requirements.txt
14+
15+
# Copy application code
16+
COPY . .
17+
18+
# Expose the application port
19+
EXPOSE 5000
20+
21+
# Health check
22+
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
23+
CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:5000/health')"
24+
25+
# Run the application
26+
CMD ["python", "app.py"]

‎README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
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

Comments
 (0)