reorganize

Author: skoulouzis

README.md

@@ -1,10 +1,36 @@
 # DevOps and Cloud Based Software  
 
-## FastAPI GitOps Starter
+# 1. Introduction 
 
-A comprehensive starter template for learning GitOps practices with FastAPI. This repository demonstrates modern software development workflows including CI/CD pipelines, code quality tools, and automated testing.
+In this tutorial will use GitOps practices with FastAPI including CI/CD pipelines, code quality tools, and automated testing.
 
-### 🎯 Learning Objectives
+## 🎓 Background Resources
+
+#### FastAPI
+- [Official Documentation](https://fastapi.tiangolo.com/)
+- [Tutorial - User Guide](https://fastapi.tiangolo.com/tutorial/)
+
+#### GitOps
+- [GitOps Principles](https://www.gitops.tech/)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+
+#### Code Quality
+- [Ruff Documentation](https://docs.astral.sh/ruff/)
+- [Black Documentation](https://black.readthedocs.io/)
+- [Pre-commit Documentation](https://pre-commit.com/)
+
+#### Testing
+- [Pytest Documentation](https://docs.pytest.org/)
+
+#### Docker
+- [Docker Documentation](https://docs.docker.com/)
+
+#### Kubernetes & Helm
+- [Kubernetes Documentation](https://kubernetes.io/docs/home/)
+- [Helm Documentation](https://helm.sh/docs/)
+- [Minikube Documentation](https://minikube.sigs.k8s.io/docs/)
+- 
+## 🎯 Learning Objectives
 
 This tutorial will teach you:
 - Building REST APIs with FastAPI
@@ -14,23 +40,23 @@ This tutorial will teach you:
 - Using pre-commit hooks for automated code validation
 - Following GitOps principles
 
-### 📋 Prerequisites
+## 📋 Prerequisites
 
 - Python 3.11 or higher
 - Git
 - Docker (optional, for containerization)
 - GitHub account
 
-### 🚀 Quick Start
+# 2. Tutorial 
 
-#### 1. Clone the Repository
+Clone the Repository
 
 ```bash
 git clone https://github.com/DevOps-and-Cloud-based-Software/fastapi-gitops.git
 cd fastapi-gitops-starter
 ```
 
-#### 2. Set Up Python Environment
+Set Up Python Environment
 
 ```bash
 # Create a virtual environment
@@ -46,41 +72,41 @@ venv\Scripts\activate
 pip install -r requirements.txt
 ```
 
-#### 3. Run the Application
+Run the Application:
 
 ```bash
 uvicorn app.main:app --reload
 ```
 
 Visit http://localhost:8000 to see your API running!
 
-#### 4. Explore the API
+Explore the API
 
 - API Documentation: http://localhost:8000/GitOps-Starter/docs
 - Root endpoint: http://localhost:8000/GitOps-Starter
 - Health check: http://localhost:8000/GitOps-Starter/health
 - List items: http://localhost:8000/GitOps-Starter/api/items
 - Get specific item: http://localhost:8000/GitOps-Starter/api/items/1
 
-### 🧪 Testing
+## 🧪 Testing
 
-#### Run Tests
+Run Tests
 
 ```bash
 pytest
 ```
 
-#### Run Tests with Coverage
+Run Tests with Coverage
 
 ```bash
 pytest --cov=app --cov-report=html
 ```
 
 View the coverage report by opening `htmlcov/index.html` in your browser.
 
-### 🔍 Code Quality
+## 🔍 Code Quality
 
-#### Linting with Ruff
+Linting with Ruff
 
 ```bash
 # Check for issues
@@ -90,7 +116,7 @@ ruff check app/ tests/
 ruff check app/ tests/ --fix
 ```
 
-#### Code Formatting with Black
+Code Formatting with Black
 
 ```bash
 # Check formatting
@@ -100,12 +126,12 @@ black --check app/ tests/
 black app/ tests/
 ```
 
-### 🪝 Pre-commit Hooks
+## 🪝 Pre-commit Hooks
 
 Pre-commit hooks automatically check your code before each commit, ensuring
 consistent code quality.
 
-#### Setup Pre-commit
+Setup Pre-commit:
 
 ```bash
 # Install pre-commit
@@ -115,7 +141,7 @@ pip install pre-commit
 pre-commit install
 ```
 
-#### Using Pre-commit
+Using Pre-commit:
 
 Pre-commit will now run automatically on `git commit`. You can also run it manually:
 
@@ -133,13 +159,13 @@ The pre-commit hooks include:
 
 ### 🐳 Docker
 
-#### Build the Docker Image
+Build the Docker Image:
 
 ```bash
 docker build -t fastapi-gitops-starter .
 ```
 
-#### Run the Container
+Run the Container:
 
 ```bash
 docker run -p 8000:8000 fastapi-gitops-starter
@@ -150,14 +176,16 @@ Access the API at http://localhost:8000/GitOps-Starter/
 ### Minikube Setup
 
 If you want to test the Kubernetes deployment locally, you can use Minikube.
-#### Install Minikube
+
+Install Minikube
 Follow the instructions at the [Minikube installation guide](https://minikube.sigs.k8s.io/docs/start/).
-#### Start Minikube with Ingress and Ingress-DNS Addons
+
+Start Minikube with Ingress and Ingress-DNS Addons:
 ```bash
 minikube start --addons=ingress,ingress-dns
 ```
 
-#### Add Minikube IP to /etc/hosts
+Add Minikube IP to /etc/hosts:
 Get the Minikube IP:
 ```bash
 minikube ip
@@ -169,24 +197,24 @@ Add the following line to your `/etc/hosts` file:
 Replace `<MINIKUBE_IP>` with the IP address obtained from the previous command.
 
 
-### ☸️ Kubernetes Deployment with Helm
+## ☸️ Kubernetes Deployment with Helm
 
 This repository includes a Helm chart for deploying the application to Kubernetes.
 
-#### Prerequisites
+### Prerequisites
 
 - Kubernetes 1.19+
 - Helm 3.0+
 
-#### Install the Helm Chart
+### Install the Helm Chart
 
 Install the chart:
 
 ```bash
 helm install my-release ./helm/fastapi-gitops-starter
 ```
 
-#### Uninstall the Helm Chart
+### Uninstall the Helm Chart
 To uninstall/delete the deployment:
 
 ```bash
@@ -198,9 +226,9 @@ Make sure you understand how to set up the Horizontal Pod Autoscaler (HPA) for
 scaling based on load and ingress configuration for accessing the application
 including host and paths.
 
-### 📚 Tutorial Exercises
+# 3. 📚 Tutorial Exercises
 
-#### Exercise 1: Add pre-commit Hooks
+## Exercise 1: Add pre-commit Hooks
 1. Open `.pre-commit-config.yaml`
 2. Add a new hook to check:
    * if we try to commit large files
@@ -210,12 +238,12 @@ including host and paths.
    * To make sure we do not commit secrets using
    * To check code style
 
-##### Questions
+## Questions
 1. What are the benefits of using pre-commit hooks in a project?
 2. How can pre-commit hooks improve code quality and consistency?
 3. How do you configure pre-commit hooks to run only on specific file types or directories?
 
-#### Exercise 2: Add a New Endpoint
+## Exercise 2: Add a New Endpoint
 
 1. Open `app/main.py`
 2. Add a new endpoint to create an item:
@@ -235,27 +263,27 @@ async def create_item(name: str, description: str):
 3. Write a test in `tests/test_main.py`
 4. Run tests to verify
 
-##### Questions
+### Questions
 1. How can you ensure that your tests cover edge cases and error scenarios?
 2. How do you run tests and view coverage reports?
 3. What are the benefits of maintaining high code coverage in a project?
 4. What other metrics can be used to assess code quality besides code coverage?
 
 
-#### Exercise 3: Add a CI Pipeline
+## Exercise 3: Add a CI Pipeline
 
 1. Open `.github/workflows/ci-cd.yml`
 2. Add a step to lint the code using Ruff
 3. Add a step to run tests with coverage. The pipeline should fail if coverage is below 80%
 4. Add a step to build the Docker image if tests pass. If we do a release, tag the image appropriately (with its version and the tag 'latest') and push it to GitHub registry
 
-##### Questions
+### Questions
 
 1. What are some strategies for rolling back deployments in case of failures in the CI/CD pipeline?
 2. How can you  ensure your application is always up to date with the latest security patches and dependencies?
 3. How can you set up automatic deployments in a production environment while minimizing downtime and ensuring KPOs are met?
 
-#### Exercise 4: Deploy on a K8s "production" Cluster
+## Exercise 4: Deploy on a K8s "production" Cluster
 
 1. Set up a Kubernetes cluster (e.g., using Minikube or a cloud provider)
 2. Deploy the application using the Helm chart
@@ -270,40 +298,14 @@ kubectl get hpa -n default -w
 ```
 7. Note how much time it takes for the pods to scale up and down based on the load
 
-##### Questions
+### Questions
 1. The auto-scaling did not work as expected. What could be the possible reasons?
 2. How does Horizontal Pod Autoscaling (HPA) work in Kubernetes?
 3. How can you add custom metrics for scaling decisions in HPA?
 4. The helm chart provides a way to perform canary and blue-green deployments. How would you set this up in a production environment? What other tools you need to use to make this work?
 5. What is the difference limits and autoscaling
 
 
-### 🎓 Learning Resources
-
-#### FastAPI
-- [Official Documentation](https://fastapi.tiangolo.com/)
-- [Tutorial - User Guide](https://fastapi.tiangolo.com/tutorial/)
-
-#### GitOps
-- [GitOps Principles](https://www.gitops.tech/)
-- [GitHub Actions Documentation](https://docs.github.com/en/actions)
-
-#### Code Quality
-- [Ruff Documentation](https://docs.astral.sh/ruff/)
-- [Black Documentation](https://black.readthedocs.io/)
-- [Pre-commit Documentation](https://pre-commit.com/)
-
-#### Testing
-- [Pytest Documentation](https://docs.pytest.org/)
-
-#### Docker
-- [Docker Documentation](https://docs.docker.com/)
-
-#### Kubernetes & Helm
-- [Kubernetes Documentation](https://kubernetes.io/docs/home/)
-- [Helm Documentation](https://helm.sh/docs/)
-- [Minikube Documentation](https://minikube.sigs.k8s.io/docs/)
-
 ### 🤝 Contributing
 
 1. Fork the repository
@@ -314,7 +316,7 @@ kubectl get hpa -n default -w
 6. Ensure all tests pass and code quality checks are successful
 7. Merge
 
-### 💡 Tips for Students
+### 💡 Tips
 
 1. **Start Simple**: Understand each component before moving to the next
 2. **Read the Logs**: When something fails, the CI/CD logs contain valuable information