Skip to content

Commit ca2887a

Browse files
maxipluxmaxiplux
committed
Add detailed documentation to README.md
1 parent da69529 commit ca2887a

1 file changed

Lines changed: 248 additions & 40 deletions

File tree

‎README.md‎

Lines changed: 248 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,278 @@
1-
DevOps FastAPI Project
1+
# DevOps FastAPI Project
22

3-
DevOps FastAPI Project
4-
======================
3+
[![Python Version](https://img.shields.io/badge/python-3.x-blue.svg)](https://www.python.org/)
4+
[![FastAPI](https://img.shields.io/badge/FastAPI-0.109.0-green.svg)](https://fastapi.tiangolo.com/)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
6+
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
57

6-
Overview
7-
--------
8+
A production-ready FastAPI application designed for experimenting with modern DevOps tools and practices. This project serves as a comprehensive learning and testing platform for DevOps methodologies in a Python environment, featuring authentication, database integration, API versioning, and containerization.
89

9-
This project is a foundational FastAPI application for experimenting with DevOps tools and practices. It's aimed at
10-
facilitating the integration of DevOps methodologies in a Python environment, serving as a learning and testing base for
11-
DevOps enthusiasts and professionals.
10+
## 📺 Demo Video
1211

13-
Goals
14-
-----
12+
**Project 4 Tutorial:** [Watch on YouTube](https://www.youtube.com/watch?v=03fnj4TSAwI)
1513

16-
* Establish a base for DevOps project testing.
17-
* Integrate various DevOps tools and practices.
18-
* Foster learning in DevOps within a Python setting.
14+
## 🎯 Project Goals
1915

20-
Getting Started
21-
---------------
16+
* **DevOps Foundation**: Establish a robust base for testing and implementing DevOps practices
17+
* **Tool Integration**: Seamlessly integrate various DevOps tools (Docker, Terraform, CI/CD)
18+
* **Learning Platform**: Foster hands-on learning for DevOps within a Python/FastAPI environment
19+
* **Best Practices**: Demonstrate modern software development and deployment patterns
20+
21+
## ✨ Features
22+
23+
### Core Functionality
24+
- **RESTful API**: Built with FastAPI for high performance and automatic OpenAPI documentation
25+
- **JWT Authentication**: Secure OAuth2 with JWT tokens for user authentication
26+
- **CRUD Operations**: Complete Create, Read, Update operations for items resource
27+
- **API Versioning**: Structured v1 API endpoints for backward compatibility
28+
- **Database Integration**: PostgreSQL database with SQLAlchemy ORM
29+
- **CORS Support**: Configured Cross-Origin Resource Sharing for frontend integration
30+
31+
### DevOps Features
32+
- **Containerization**: Docker and Docker Compose configurations
33+
- **Infrastructure as Code**: Terraform configuration for cloud deployment
34+
- **Testing Suite**: Comprehensive pytest-based test coverage
35+
- **Code Quality**: Integrated linting (flake8, pylint) and formatting (autopep8)
36+
- **Environment Configuration**: Environment variable based configuration management
37+
38+
### API Endpoints
39+
40+
#### Authentication
41+
- `POST /token` - Login with username/password to receive JWT access token
42+
- `GET /users/me/` - Get current authenticated user profile
43+
44+
#### Items (Protected - Requires Authentication)
45+
- `GET /items/` - List items with pagination (skip, limit parameters)
46+
- `POST /items/` - Create a new item
47+
- `PATCH /items/{id}` - Update an existing item
48+
49+
#### Documentation
50+
- `GET /docs` - Interactive Swagger UI API documentation (auto-generated)
51+
- `GET /redoc` - ReDoc API documentation (auto-generated)
52+
53+
## 🏗️ Project Structure
54+
55+
```
56+
api-python-project-devops-fast-api21/
57+
├── app/
58+
│ ├── config/ # Configuration files (database, settings)
59+
│ ├── models/ # Database models and Pydantic schemas
60+
│ ├── repositories/ # Data access layer (repository pattern)
61+
│ ├── routers/ # API route handlers
62+
│ │ └── v1/ # Version 1 API endpoints
63+
│ ├── security/ # Security utilities
64+
│ └── services/ # Business logic layer
65+
├── tests/ # Test suite
66+
│ ├── test_auth.py # Authentication tests
67+
│ └── test_items.py # Items endpoint tests
68+
├── main.py # Application entry point
69+
├── call_db.py # Database connection utilities
70+
├── Dockerfile # Docker image configuration
71+
├── docker-compose.yml # Multi-container Docker setup
72+
├── main.tf # Terraform infrastructure configuration
73+
├── requirements.txt # Python dependencies
74+
└── README.md # This file
75+
```
76+
77+
## 🛠️ Technology Stack
78+
79+
### Core Framework
80+
- **FastAPI** (0.109.0) - Modern, fast web framework for building APIs
81+
- **Uvicorn** (0.25.0) - ASGI server for running FastAPI
82+
- **Pydantic** (2.5.3) - Data validation using Python type annotations
83+
84+
### Database
85+
- **SQLAlchemy** (2.0.25) - SQL toolkit and ORM
86+
- **PostgreSQL** - Primary database (via psycopg2-binary)
87+
88+
### Authentication & Security
89+
- **python-jose** (3.3.0) - JWT token creation and validation
90+
- **passlib** (1.7.4) & **bcrypt** (4.1.2) - Password hashing
91+
- **cryptography** (41.0.7) - Cryptographic recipes
92+
93+
### Development & Testing
94+
- **pytest** (7.4.4) - Testing framework
95+
- **pytest-html** (4.1.1) - HTML test reports
96+
- **flake8** (7.0.0) - Code linting
97+
- **pylint** (3.0.3) - Code analysis
98+
- **autopep8** (2.0.4) - Code formatting
99+
100+
### DevOps Tools
101+
- **Docker** & **Docker Compose** - Containerization
102+
- **Terraform** - Infrastructure as Code
103+
- **Gunicorn** (20.1.0) - WSGI HTTP server for production
104+
105+
## 🚀 Getting Started
22106

23107
### Prerequisites
24108

25-
* Python 3.x
26-
* Docker (for containerization)
109+
Ensure you have the following installed:
110+
- **Python 3.x** (3.9 or higher recommended)
111+
- **pip** (Python package manager)
112+
- **Docker** and **Docker Compose** (for containerized deployment)
113+
- **PostgreSQL** (if running locally without Docker)
27114

28115
### Installation
29116

30-
Clone the repo:
117+
1. **Clone the repository:**
118+
```bash
119+
git clone https://github.com/maxiplux/api-python-project-devops-fast-api.git
120+
cd api-python-project-devops-fast-api21
121+
```
122+
123+
2. **Install dependencies:**
124+
```bash
125+
pip install -r requirements.txt
126+
```
127+
128+
3. **Set up environment variables:**
129+
130+
Create a `.env` file or export the following variables:
131+
```bash
132+
DB_USERNAME=postgres
133+
DB_PASSWORD=postgres
134+
DB_HOST=localhost
135+
DB_NAME=postgres
136+
SECRET_KEY=your-secret-key-here
137+
ACCESS_TOKEN_EXPIRE_MINUTES=30
138+
```
139+
140+
### Running the Application
141+
142+
#### Option 1: Local Development
143+
144+
Run the FastAPI application with hot-reload:
145+
```bash
146+
uvicorn main:app --reload
147+
```
148+
149+
The API will be available at:
150+
- **API**: http://localhost:8000
151+
- **Interactive Docs**: http://localhost:8000/docs
152+
- **Alternative Docs**: http://localhost:8000/redoc
153+
154+
#### Option 2: Docker (Single Container)
155+
156+
Build and run the Docker container:
157+
```bash
158+
docker build -t fastapi-devops .
159+
docker run -p 8000:8000 \
160+
-e DB_USERNAME=your_username \
161+
-e DB_PASSWORD=your_password \
162+
-e DB_HOST=your_host \
163+
-e DB_NAME=your_db_name \
164+
fastapi-devops
165+
```
166+
167+
#### Option 3: Docker Compose (Recommended)
168+
169+
Run the complete stack with PostgreSQL database:
170+
```bash
171+
docker-compose up -d
172+
```
173+
174+
The application will be available at:
175+
- **API**: http://localhost:8080
176+
- **PostgreSQL**: localhost:5432
177+
178+
To stop the services:
179+
```bash
180+
docker-compose down
181+
```
182+
183+
## 🧪 Testing
184+
185+
Run the test suite using pytest:
186+
187+
```bash
188+
# Run all tests
189+
pytest
190+
191+
# Run with coverage report
192+
pytest --cov=app
193+
194+
# Run with HTML report
195+
pytest --html=report.html
196+
197+
# Run specific test file
198+
pytest tests/test_auth.py
199+
```
200+
201+
## 🔐 Authentication Usage
202+
203+
1. **Obtain an access token:**
204+
```bash
205+
curl -X POST "http://localhost:8000/token" \
206+
-H "Content-Type: application/json" \
207+
-d '{"username":"testuser","password":"testpass"}'
208+
```
31209

32-
git clone https://github.com/maxiplux/api-python-project-devops-fast-api.git
210+
2. **Use the token for authenticated requests:**
211+
```bash
212+
curl -X GET "http://localhost:8000/items/" \
213+
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
214+
```
33215

34-
Install dependencies:
216+
## 🔧 Environment Variables
35217

36-
pip install -r requirements.txt
218+
| Variable | Description | Default | Required |
219+
|----------|-------------|---------|----------|
220+
| `DB_USERNAME` | PostgreSQL username | postgres | Yes |
221+
| `DB_PASSWORD` | PostgreSQL password | postgres | Yes |
222+
| `DB_HOST` | Database host | localhost | Yes |
223+
| `DB_NAME` | Database name | postgres | Yes |
224+
| `SECRET_KEY` | JWT secret key | - | Yes |
225+
| `ACCESS_TOKEN_EXPIRE_MINUTES` | Token expiration time | 30 | No |
37226

38-
### Running the App
227+
## 🐛 Troubleshooting
39228

40-
Locally:
229+
### Database Connection Issues
230+
- Verify PostgreSQL is running: `docker-compose ps`
231+
- Check environment variables are correctly set
232+
- Ensure the database exists and user has proper permissions
41233

42-
uvicorn main:app --reload
234+
### Port Already in Use
235+
```bash
236+
# Check what's using port 8000
237+
netstat -ano | findstr :8000 # Windows
238+
lsof -i :8000 # Linux/Mac
43239

44-
Using Docker:
240+
# Kill the process or use a different port
241+
uvicorn main:app --reload --port 8001
242+
```
45243

46-
docker build -t fastapi-devops .
47-
docker run -p 8000:8000 -e DB_USERNAME=your_username -e DB_PASSWORD=your_password -e DB_HOST=your_host -e DB_NAME=your_db_name fastapi-devops
244+
### Import Errors
245+
```bash
246+
# Reinstall dependencies
247+
pip install -r requirements.txt --force-reinstall
248+
```
48249

49-
#Video with the answer to project 4:
50-
## https://www.youtube.com/watch?v=03fnj4TSAwI
51-
250+
## 🤝 Contributing
52251

252+
Contributions are welcome! Please follow these steps:
53253

254+
1. Fork the repository
255+
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
256+
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
257+
4. Push to the branch (`git push origin feature/AmazingFeature`)
258+
5. Open a Pull Request
54259

260+
### Development Guidelines
261+
- Follow PEP 8 style guidelines
262+
- Write tests for new features
263+
- Update documentation as needed
264+
- Ensure all tests pass before submitting PR
55265

56-
Contributing
57-
------------
266+
## 📝 License
58267

59-
Feel free to fork, modify, and send a pull request. Contributions are welcome!
268+
This project is licensed under the [MIT License](LICENSE) - see the LICENSE file for details.
60269

61-
License
62-
-------
270+
## 📧 Contact
63271

64-
[MIT License](LICENSE)
272+
**Maintainer**: maxiplux
273+
**Email**: maxiplux@gmail.com
274+
**GitHub**: [@maxiplux](https://github.com/maxiplux)
65275

66-
Contact
67-
-------
276+
---
68277

69-
Your Name
70-
maxiplux@gmail.com
278+
**⭐ If you find this project helpful, please consider giving it a star!**

0 commit comments

Comments
 (0)