{"id":33235880,"url":"https://github.com/williamle92/kubernetes_traefik_fastapi","last_synced_at":"2026-04-13T00:09:06.803Z","repository":{"id":323232135,"uuid":"1092572064","full_name":"williamle92/kubernetes_traefik_fastapi","owner":"williamle92","description":"FastAPI backend with Celery task queue, JWT authentication, and cloud-native Kubernetes deployment","archived":false,"fork":false,"pushed_at":"2025-11-08T22:01:39.000Z","size":117,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-08T23:31:24.932Z","etag":null,"topics":["celery","docker","dockerfile","fastapi","helm","kubernetes","microservices","postgresql","redis"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/williamle92.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T21:53:07.000Z","updated_at":"2025-11-08T22:01:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/williamle92/kubernetes_traefik_fastapi","commit_stats":null,"previous_names":["williamle92/kubernetes_traefik_fastapi"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/williamle92/kubernetes_traefik_fastapi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamle92%2Fkubernetes_traefik_fastapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamle92%2Fkubernetes_traefik_fastapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamle92%2Fkubernetes_traefik_fastapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamle92%2Fkubernetes_traefik_fastapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamle92","download_url":"https://codeload.github.com/williamle92/kubernetes_traefik_fastapi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamle92%2Fkubernetes_traefik_fastapi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284750955,"owners_count":27057456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-16T02:00:05.974Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["celery","docker","dockerfile","fastapi","helm","kubernetes","microservices","postgresql","redis"],"created_at":"2025-11-16T18:01:19.989Z","updated_at":"2025-11-16T18:02:54.473Z","avatar_url":"https://github.com/williamle92.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyperion - Backend API Project\n\nA modern, production-ready backend API built with FastAPI and deployed on Kubernetes. This project demonstrates industry-standard practices for building scalable web applications with asynchronous task processing.\n\n## 📚 Table of Contents\n\n- [What is This Project?](#what-is-this-project)\n- [Technology Stack Explained](#technology-stack-explained)\n- [Architecture Overview](#architecture-overview)\n- [Project Structure](#project-structure)\n- [Key Concepts for Beginners](#key-concepts-for-beginners)\n- [Prerequisites](#prerequisites)\n- [Local Development Setup](#local-development-setup)\n- [Running the Application](#running-the-application)\n- [Database Migrations](#database-migrations)\n- [Kubernetes Deployment](#kubernetes-deployment)\n- [API Documentation](#api-documentation)\n\n---\n\n## What is This Project?\n\nHyperion is a backend API application that provides:\n- **User Authentication \u0026 Management**: Register, login, and manage user accounts\n- **RESTful API**: Clean, well-structured endpoints following REST principles\n- **Background Task Processing**: Handle long-running tasks without blocking API requests\n- **Database Management**: Persistent data storage with automatic migrations\n- **Cloud-Native Deployment**: Production-ready Kubernetes configuration\n\nThis project serves as a template or learning resource for building modern web applications.\n\n---\n\n## Technology Stack Explained\n\n### Core Application\n\n**FastAPI** - The Web Framework\n- A modern Python framework for building APIs\n- Automatically generates interactive API documentation\n- Fast performance with async/await support\n- Built-in data validation using Pydantic\n\n**SQLAlchemy** - Database Toolkit\n- An ORM (Object-Relational Mapper) that lets you work with databases using Python objects instead of SQL\n- Example: Instead of writing SQL queries, you write Python code like `User.query.filter_by(email=\"user@example.com\")`\n\n**Alembic** - Database Migration Tool\n- Manages changes to your database schema over time\n- Think of it as \"version control for your database\"\n- Allows you to upgrade/downgrade database structure safely\n\n**PostgreSQL** - The Database\n- A powerful, open-source relational database\n- Stores all your application data (users, etc.)\n- Supports complex queries and transactions\n\n### Background Processing\n\n**Celery** - Task Queue\n- Handles tasks that take a long time (sending emails, processing data, etc.)\n- Runs tasks in the background so your API responds quickly\n- Example: When a user signs up, the API responds immediately while Celery sends a welcome email in the background\n\n**Redis** - Message Broker \u0026 Cache\n- Acts as a messenger between your API and Celery workers\n- Stores tasks in a queue until workers can process them\n- Also used for caching to speed up your application\n\n### Authentication \u0026 Security\n\n**Python-JOSE** - JWT Token Handling\n- Creates and validates JWT (JSON Web Tokens)\n- JWTs are like secure \"tickets\" that prove a user is logged in\n- Used for stateless authentication (no need to store sessions on the server)\n\n**Passlib \u0026 Bcrypt** - Password Security\n- Safely hashes (encrypts) passwords before storing them\n- Even if someone steals your database, they can't read the passwords\n- Industry-standard security practice\n\n### Development \u0026 Deployment\n\n**Docker** - Containerization\n- Packages your application with all its dependencies\n- Ensures it runs the same way everywhere (your laptop, server, cloud)\n- Think of it as a \"shipping container\" for software\n\n**Kubernetes (K8s)** - Container Orchestration\n- Manages multiple containers running your application\n- Automatically handles scaling, restarts, and load balancing\n- Production-grade deployment solution\n\n**Helm** - Kubernetes Package Manager\n- Makes it easier to deploy and manage Kubernetes applications\n- Uses templates to configure your deployment\n- Think of it as \"apt-get\" or \"npm\" for Kubernetes\n\n---\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                        KUBERNETES CLUSTER                   │\n│                                                             │\n│  ┌────────────────────┐         ┌──────────────────────┐    │\n│  │   Ingress/Traefik  │         │   ConfigMap/Secrets  │    │\n│  │  (Load Balancer)   │         │   (Configuration)    │    │\n│  └──────────┬─────────┘         └──────────────────────┘    │\n│             │                                               │\n│  ┌──────────▼─────────┐                                     │\n│  │   API Pods (x3)    │◄────┐                               │\n│  │   (FastAPI App)    │     │                               │\n│  └──────────┬─────────┘     │                               │\n│             │               │                               │\n│             │          Environment                          │\n│             │          Variables                            │\n│             │                                               │\n│  ┌──────────▼─────────┐     │                               │\n│  │   PostgreSQL DB    │     │                               │\n│  │   (Data Storage)   │     │                               │\n│  └────────────────────┘     │                               │\n│                             │                               │\n│  ┌─────────────────────┐    │                               │\n│  │  Worker Pods (x2)   │◄───┘                               │\n│  │  (Celery Workers)   │                                    │\n│  └──────────┬──────────┘                                    │\n│             │                                               │\n│  ┌──────────▼──────────┐                                    │\n│  │       Redis         │                                    │\n│  │  (Message Broker)   │                                    │\n│  └─────────────────────┘                                    │\n└─────────────────────────────────────────────────────────────┘\n\nRequest Flow:\n1. User sends HTTP request → Ingress (Traefik)\n2. Ingress routes to API Pod\n3. API processes request using PostgreSQL\n4. If background task needed → queued in Redis\n5. Worker picks up task from Redis and processes it\n```\n\n**Why This Architecture?**\n\n- **Multiple API Pods (3)**: If one crashes, others keep serving requests\n- **Separate Worker Pods (2)**: Background tasks don't slow down API responses\n- **Redis Queue**: Decouples API from workers, allowing independent scaling\n- **PostgreSQL**: Reliable data persistence\n- **Traefik Ingress**: Single entry point with HTTPS support\n\n---\n\n## Project Structure\n\n```\nbackend/\n├── api/                        # Main application code\n│   └── backend/\n│       ├── main.py            # FastAPI application entry point\n│       ├── configs.py         # Configuration management\n│       ├── models/            # Database models (SQLAlchemy)\n│       │   ├── users.py       # User model and roles\n│       │   └── base.py        # Base model class\n│       ├── routers/           # API endpoints\n│       │   ├── auth.py        # Login, register endpoints\n│       │   └── users.py       # User management endpoints\n│       ├── pydantic/          # Request/Response schemas\n│       │   ├── auth.py        # Auth data validation\n│       │   └── users.py       # User data validation\n│       ├── dependencies/      # Shared dependencies\n│       │   └── auth.py        # Authentication helpers\n│       ├── worker/            # Background task processing\n│       │   └── tasks.py       # Celery tasks\n│       └── migrations/        # Database migrations (Alembic)\n│\n├── kubernetes/                # Kubernetes deployment configs\n│   ├── hyperion/             # Helm chart for the application\n│   │   ├── Chart.yaml        # Chart metadata\n│   │   ├── values.yaml       # Configuration values\n│   │   ├── configmap.yaml    # Non-sensitive config\n│   │   └── templates/        # K8s resource templates\n│   │       ├── deployment.yaml        # API pods\n│   │       ├── worker-deployment.yaml # Worker pods\n│   │       ├── service.yaml           # Internal networking\n│   │       └── ingress.yaml           # External access\n│   ├── redis/                # Redis configuration\n│   └── traefik/              # Ingress controller config\n│\n├── Dockerfile                # Container image definition\n├── pyproject.toml           # Python dependencies (Poetry)\n├── alembic.ini              # Database migration config\n├── .env                     # Environment variables (local)\n└── README.md                # This file\n```\n\n---\n\n## Key Concepts\n\n### 1. **API (Application Programming Interface)**\nAn API is how different software applications talk to each other. This project provides a REST API - a set of URLs that respond with data.\n\nExample:\n- `GET /v1/api/users` - Get list of users\n- `POST /v1/api/auth/login` - Log in a user\n\n### 2. **Asynchronous Programming (async/await)**\nFastAPI uses async code to handle multiple requests simultaneously without waiting for slow operations (like database queries) to complete.\n\n```python\nasync def get_user():  # Can handle other requests while waiting\n    user = await database.get_user()  # Wait for database\n    return user\n```\n\n### 3. **ORM (Object-Relational Mapping)**\nInstead of writing SQL, you work with Python objects:\n\n```python\n# Without ORM (raw SQL)\ncursor.execute(\"SELECT * FROM users WHERE email = ?\", email)\n\n# With ORM (SQLAlchemy)\nuser = User.query.filter_by(email=email).first()\n```\n\n### 4. **Database Migrations**\nWhen you change your database structure (add a column, create a table), migrations record these changes:\n\n```bash\n# Create a migration for changes\npoetry run task generate-migrations\n\n# Apply migrations to database\npoetry run task commit-migrations\n```\n\n### 5. **Environment Variables**\nConfiguration that changes between environments (local, staging, production) is stored in `.env` files:\n\n```\nPG_HOST=localhost      # Database location\nSECRET_KEY=your-secret # JWT signing key\n```\n\n### 6. **Containers \u0026 Pods**\n- **Container**: Your app + dependencies packaged together (Docker)\n- **Pod**: Smallest deployable unit in Kubernetes (can contain 1+ containers)\n- **Deployment**: Manages multiple identical pods\n\n### 7. **JWT (JSON Web Tokens)**\nA secure way to verify a user's identity:\n\n1. User logs in with username/password\n2. Server creates a JWT token (cryptographically signed)\n3. User sends this token with each request\n4. Server verifies the token to identify the user\n\n### 8. **Message Queue (Celery + Redis)**\nWhen you have tasks that take a long time:\n\n1. API receives request → immediately queues task in Redis → responds to user\n2. Worker picks up task from Redis → processes it in background\n3. User doesn't have to wait\n\n---\n\n## Prerequisites\n\nBefore you begin, ensure you have installed:\n\n- **Python 3.11+**: [Download](https://www.python.org/downloads/)\n- **Poetry**: Python dependency manager\n  ```bash\n  curl -sSL https://install.python-poetry.org | python3 -\n  ```\n- **Docker Desktop**: For containerization [Download](https://www.docker.com/products/docker-desktop/)\n- **PostgreSQL**: Database (or use Docker)\n- **Redis**: Message broker (or use Docker)\n- **kubectl**: Kubernetes CLI (for deployment)\n- **Helm**: Kubernetes package manager (for deployment)\n\n---\n\n## Local Development Setup\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/williamle92/kubernetes_traefik_fastapi.git\ncd backend\n```\n\n### 2. Install Dependencies\n\n```bash\n# Install Python dependencies\npoetry install\n```\n\n### 3. Set Up Environment Variables\n\nCreate a `.env` file in the project root:\n\n```bash\n# Database Configuration\nPG_HOST=localhost\nPG_USER=postgres\nPG_PASSWORD=your_password\nPG_DB=your_db_name\nPG_PORT=5432\n\n# Authentication\nSECRET_KEY=your-super-secret-key-change-this\nSALT=your-salt-value-change-this\nALGORITHM=HS256\n\n# Redis Configuration\nREDIS_HOST=localhost\nREDIS_PASSWORD=\n```\n\n### 4. Start Required Services\n\n**Option A: Using Docker Compose** (Recommended for beginners)\n```bash\ncd api\ndocker compose up -d postgres redis\n```\n\n**Option B: Install Locally**\n- Install PostgreSQL and create a database named `hyperion`\n- Install Redis and start it\n\n### 5. Run Database Migrations\n\n```bash\n# Generate migration files (if schema changed)\npoetry run task generate-migrations\n\n# Apply migrations to create tables\npoetry run task commit-migrations\n```\n\n---\n\n## Running the Application\n\n### Start the API Server\n\n```bash\npoetry run task app\n```\n\nThe API will be available at: `http://localhost:8000`\n\n### Start the Celery Worker (for background tasks)\n\nIn a separate terminal:\n\n```bash\npoetry run task worker\n```\n\n### Access API Documentation\n\nFastAPI automatically generates interactive docs:\n\n- **Swagger UI**: http://localhost:8000/swagger\n- **ReDoc**: http://localhost:8000/docs\n\nThese allow you to test API endpoints directly in your browser!\n\n---\n\n## Database Migrations\n\nAlembic manages your database schema changes:\n\n### Create a New Migration\n\nAfter modifying models in `api/backend/models/`:\n\n```bash\npoetry run task generate-migrations\n```\n\nThis creates a new migration file in `api/backend/migrations/versions/`\n\n### Apply Migrations\n\n```bash\npoetry run task commit-migrations\n```\n\n### Rollback Last Migration\n\n```bash\npoetry run task rollback-migrations\n```\n\n### How It Works\n\n1. You change a model (e.g., add a field to `User`)\n2. Generate migration → Alembic detects the change\n3. Commit migration → Database is updated\n4. All team members can apply the same migration to stay in sync\n\n---\n\n### Understanding the Deployment\n\n- **API Deployment**: 3 replicas for high availability\n- **Worker Deployment**: 2 replicas for background tasks\n- **Redis**: Message broker for Celery\n- **PostgreSQL**: Database (configure separately or use managed service)\n- **Traefik**: Routes external traffic to your API\n- **ConfigMap**: Non-sensitive configuration\n- **Secrets**: Sensitive data (passwords, keys)\n\n---\n\n\n## Learning Resources\n\n- **FastAPI**: https://fastapi.tiangolo.com/\n- **SQLAlchemy**: https://docs.sqlalchemy.org/\n- **Celery**: https://docs.celeryq.dev/\n- **Kubernetes**: https://kubernetes.io/docs/home/\n- **Helm**: https://helm.sh/docs/\n- **Docker**: https://docs.docker.com/\n\n---\n\n## License\n\nThis project is for educational purposes.\n\n## Contributing\n\nContributions welcome! Please open an issue or submit a pull request.\n\n---\n\n**Questions?** Check the API docs at `/swagger` or open an issue on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamle92%2Fkubernetes_traefik_fastapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamle92%2Fkubernetes_traefik_fastapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamle92%2Fkubernetes_traefik_fastapi/lists"}