{"id":34626180,"url":"https://github.com/atick-faisal/fastapi-docker-traefik","last_synced_at":"2026-04-11T09:01:07.123Z","repository":{"id":304992612,"uuid":"1002297860","full_name":"atick-faisal/fastapi-docker-traefik","owner":"atick-faisal","description":"Hello World using FastAPI, Docker Compose and Traefik - SSL and Load Balancing","archived":false,"fork":false,"pushed_at":"2026-04-07T21:10:37.000Z","size":127,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T23:13:00.238Z","etag":null,"topics":["cloudrun","docker","docker-compose","fastapi","gcp","load-balancer","ssl","terraform","traefik","vps"],"latest_commit_sha":null,"homepage":"https://atick.dev","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atick-faisal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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},"funding":{"ko_fi":"atickfaisal","patreon":"atick"}},"created_at":"2025-06-15T06:41:19.000Z","updated_at":"2026-03-11T18:58:09.000Z","dependencies_parsed_at":"2025-07-17T21:08:12.489Z","dependency_job_id":"c3c1f088-1e35-4f1a-8da4-ee201a7c37e7","html_url":"https://github.com/atick-faisal/fastapi-docker-traefik","commit_stats":null,"previous_names":["atick-faisal/fastapi-docker-traefik"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/atick-faisal/fastapi-docker-traefik","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atick-faisal%2Ffastapi-docker-traefik","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atick-faisal%2Ffastapi-docker-traefik/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atick-faisal%2Ffastapi-docker-traefik/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atick-faisal%2Ffastapi-docker-traefik/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atick-faisal","download_url":"https://codeload.github.com/atick-faisal/fastapi-docker-traefik/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atick-faisal%2Ffastapi-docker-traefik/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31674624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T08:18:19.405Z","status":"ssl_error","status_checked_at":"2026-04-11T08:17:08.892Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cloudrun","docker","docker-compose","fastapi","gcp","load-balancer","ssl","terraform","traefik","vps"],"created_at":"2025-12-24T15:56:10.832Z","updated_at":"2026-04-11T09:01:07.115Z","avatar_url":"https://github.com/atick-faisal.png","language":"HCL","funding_links":["https://ko-fi.com/atickfaisal","https://patreon.com/atick"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003ca href=\"https://donate.unrwa.org/int/en/general\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/Safouene1/support-palestine-banner/master/banner-support.svg\" alt=\"Support Palestine\" style=\"width: 100%;\"\u003e\u003c/a\u003e\u003c/div\u003e\n\n# 🚀 FastAPI Docker Traefik Starter Template\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/FastAPI-Async%20Python%203.13-0ba360?style=for-the-badge\u0026colorA=363a4f\u0026colorB=a6da95\u0026logo=fastapi\u0026logoColor=white\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Dockerized-Easy%20Deploy%20App-2396ed?style=for-the-badge\u0026colorA=363a4f\u0026colorB=89dceb\u0026logo=docker\u0026logoColor=white\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Traefik-HTTPS%20+%20Load%20Balancing-f5a97f?style=for-the-badge\u0026colorA=363a4f\u0026colorB=f5a97f\u0026logo=traefikmesh\u0026logoColor=white\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/GitHub%20Actions-CI%2FCD%20Ready-8aadf4?style=for-the-badge\u0026colorA=363a4f\u0026colorB=b7bdf8\u0026logo=githubactions\u0026logoColor=white\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Let's%20Encrypt-Automated%20SSL-e0af68?style=for-the-badge\u0026colorA=363a4f\u0026colorB=e0af68\u0026logo=letsencrypt\u0026logoColor=white\"/\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Google%20Cloud%20Run-Serverless%20Deploy-4285F4?style=for-the-badge\u0026colorA=363a4f\u0026colorB=8aadf4\u0026logo=googlecloud\u0026logoColor=white\"/\u003e\n\u003c/p\u003e\n\nProduction-ready FastAPI template with **two deployment options**: traditional VPS with Traefik or serverless Google\nCloud Run. Choose your path below! 🚀\n\n\u003e [!NOTE]\n\u003e This template supports two completely different deployment strategies. Choose the one that best fits your needs and\n\u003e infrastructure preferences.\n\n## ✨ Features\n\n* 🐳 **Dockerized FastAPI** with Python 3.13 and `uv` for fast builds\n* 🔄 **GitHub Actions CI/CD** with automated testing and deployment\n* 🔒 **HTTPS by default** (Let's Encrypt for VPS, Google-managed for Cloud Run)\n* 📦 **Multi-registry support** (GHCR + Google Artifact Registry)\n* ⚡ **Two deployment paths** - choose what fits your needs\n\n---\n\n## 📁 Project Structure\n\n```\n.\n├── app/                  # Your FastAPI app\n│   └── main.py           # Sample FastAPI \"Hello World\"\n├── docker-compose.yml    # Services: Traefik + App (VPS only)\n├── Dockerfile            # Multi-stage build with uv\n├── pyproject.toml        # Project + dependency config\n├── infra/cloud-run/      # Terraform for GCP Cloud Run\n│   ├── main.tf\n│   ├── variables.tf\n│   └── terraform.tfvars\n├── .env.example          # Sample environment vars\n├── .github/              # GitHub Actions workflows\n```\n\n---\n\n## 🎯 Choose Your Deployment Path\n\n\u003e [!IMPORTANT]\n\u003e You must choose **only one** deployment path. The GitHub Actions workflow is configured to use either VPS or Cloud\n\u003e Run, not both simultaneously.\n\n### 🖥️ Option 1: VPS Deployment (Traditional)\n\n**Best for:** Full control, custom domains, existing infrastructure\n\n- ✅ Complete server control\n- ✅ Traefik load balancer with Let's Encrypt SSL\n- ✅ Docker Compose orchestration\n- ✅ SSH-based deployment\n\n**[👉 Go to VPS Setup](#-vps-deployment-path)**\n\n### ☁️ Option 2: Google Cloud Run (Serverless)\n\n**Best for:** Scalability, simplicity, pay-per-use\n\n- ✅ Serverless autoscaling (0 to N instances)\n- ✅ Google-managed HTTPS and load balancing\n- ✅ Terraform Infrastructure-as-Code\n- ✅ No server maintenance\n\n**[👉 Go to Cloud Run Setup](#%EF%B8%8F-cloud-run-deployment-path)**\n\n---\n\n# 🖥️ VPS Deployment Path\n\n## Prerequisites\n\n\u003e [!WARNING]\n\u003e Ensure your domain's DNS A record points to your VPS IP address before starting. SSL certificate generation will fail\n\u003e without proper DNS configuration.\n\n* Linux VPS (Ubuntu 22.04 recommended)\n* Domain name pointed to your VPS IP\n* Docker \u0026 Docker Compose installed\n\n## Step 1: VPS Server Setup\n\n### Install Docker\n\n```bash\n# Install Docker\ncurl -fsSL https://get.docker.com -o get-docker.sh\nsh get-docker.sh\n```\n\n\u003e [!IMPORTANT]\n\u003e Make sure to add Docker to your user group so that you can run it without root access.\n\u003e ```bash\n\u003e sudo usermod -aG docker $USER\n\u003e newgrp docker\n\u003e ```\n\n### Create Deployment User\n\n\u003e [!TIP]\n\u003e Using a dedicated deployment user improves security by limiting privileges and isolating deployment operations.\n\n```bash\n# Create non-root user for deployments\nsudo adduser deployer\nsudo usermod -aG sudo deployer\nsudo usermod -aG docker deployer\n```\n\n### Configure SSH Access\n\n```bash\n# Generate SSH key pair (on your local machine)\nssh-keygen -t ed25519 -C \"your_email@example.com\"\n\n# Copy public key to VPS\nssh-copy-id deployer@your-vps-ip\n```\n\n\u003e [!CAUTION]\n\u003e Test SSH key authentication before disabling password authentication. Keep a backup terminal session open until you\n\u003e confirm key-based login works.\n\n### Harden SSH Security\n\n```bash\n# Edit SSH config\nsudo nano /etc/ssh/sshd_config\n\n# Add these settings:\n# PermitRootLogin no\n# PasswordAuthentication no\n\n# Restart SSH service\nsudo systemctl restart ssh\n```\n\n### Setup Firewall\n\n\u003e [!WARNING]\n\u003e Configure the firewall carefully. Incorrect settings can lock you out of your server.\n\n```bash\nsudo ufw default deny incoming\nsudo ufw default allow outgoing\nsudo ufw allow OpenSSH\nsudo ufw allow 80\nsudo ufw allow 443\nsudo ufw enable\n```\n\n### Create Let's Encrypt Directory\n\n```bash\nsudo mkdir -p /etc/letsencrypt\nsudo chown deployer:deployer /etc/letsencrypt\nsudo chmod 700 /etc/letsencrypt\n```\n\n\u003e [!NOTE]\n\u003e This directory will store SSL certificates generated by Let's Encrypt through Traefik.\n\n## Step 2: Configure Your Project\n\n### Clone and Setup\n\n```bash\ngit clone https://github.com/atick-faisal/fastapi-docker-traefik.git\ncd fastapi-docker-traefik\ncp .env.example .env\n```\n\n### Edit Environment Variables\n\n\u003e [!IMPORTANT]\n\u003e Replace these values with your actual domain and email address:\n\n```env\nDOMAIN_NAME=yourdomain.com\nACME_EMAIL=you@example.com\n```\n\n## Step 3: GitHub Actions Setup\n\n### Required GitHub Secrets\n\n\u003e [!CAUTION]\n\u003e Keep these secrets secure. Never commit them to your repository or share them publicly.\n\n| Secret Name   | Description                   |\n|---------------|-------------------------------|\n| `VPS_HOST`    | Your VPS IP address or domain |\n| `VPS_USER`    | VPS username (e.g., deployer) |\n| `VPS_SSH_KEY` | Private SSH key content       |\n\n### Enable VPS Deployment\n\n\u003e [!IMPORTANT]\n\u003e In `.github/workflows/deploy.yml`, ensure the `deploy-vps` job is **uncommented** and `deploy-cloud-run` is *\n*commented out**.\n\n## Step 4: Deploy\n\n\u003e [!TIP]\n\u003e Test your Docker setup locally before pushing to production:\n\n```bash\n# Test locally first\ndocker compose up --build\n```\n\n```bash\n# Push to trigger deployment\ngit add .\ngit commit -m \"Configure VPS deployment\"\ngit push origin main\n```\n\nYour app will be available at `https://yourdomain.com` with automatic HTTPS!\n\n\u003e [!NOTE]\n\u003e SSL certificate generation may take a few minutes on the first deployment. Check Traefik logs if you encounter issues.\n\n### VPS Management Commands\n\n```bash\n# View logs\ndocker compose logs -f\n\n# Restart services  \ndocker compose restart\n\n# Update deployment\ngit pull origin main\ndocker compose up -d --build\n\n# Clean up\ndocker image prune -f\n```\n\n---\n\n# ☁️ Cloud Run Deployment Path\n\n## Prerequisites\n\n\u003e [!WARNING]\n\u003e Google Cloud Run may incur charges based on usage. Review Google Cloud pricing before proceeding.\n\n* Google Cloud Platform account\n* `gcloud` CLI [installed](https://cloud.google.com/sdk/docs/install)\n  and [authenticated](https://cloud.google.com/docs/authentication/gcloud)\n* Terraform [installed](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)\n* Domain name (optional, Cloud Run provides a URL)\n\n\u003e [!TIP]\n\u003e Enable the required APIs in your GCP project:\n\u003e ```bash\n\u003e gcloud services enable run.googleapis.com artifactregistry.googleapis.com\n\u003e ```\n\n## Step 1: Configure Infrastructure\n\n### Edit Terraform Variables\n\n```bash\ncp infra/cloud-run/terraform.tfvars.example infra/cloud-run/terraform.tfvars\n```\n\nEdit `infra/cloud-run/terraform.tfvars`:\n\n\u003e [!IMPORTANT]\n\u003e Replace all placeholder values with your actual project information:\n\n```hcl\nproject_id         = \"your-gcp-project-id\"\nregion             = \"me-central1\"\ngithub_repo        = \"fastapi-docker-traefik\"\ngithub_repo_owner  = \"your-github-username\"\nservice_account_id = \"github-actions-sa\"\ngar_repo_name      = \"fastapi-docker-traefik\"\n```\n\n### Deploy Infrastructure\n\n\u003e [!CAUTION]\n\u003e Review the Terraform plan carefully before applying. This will create billable resources in your GCP project.\n\n```bash\ncd infra/cloud-run\nterraform init\nterraform plan\nterraform apply\n```\n\nThis creates:\n\n- Workload Identity Pool for GitHub Actions\n- Service Account with required permissions\n- Artifact Registry repository\n- IAM bindings\n\n\u003e [!NOTE]\n\u003e Terraform will output the values needed for GitHub secrets configuration.\n\n## Step 2: GitHub Actions Setup\n\n### Required GitHub Secrets\n\n\u003e [!IMPORTANT]\n\u003e Terraform output will show you the exact values needed. Copy them precisely:\n\n| Secret Name                 | Description                    |\n|-----------------------------|--------------------------------|\n| `GCP_PROJECT_ID`            | Your Google Cloud project ID   |\n| `REGION`                    | GCP region (e.g., us-central1) |\n| `GAR_REPOSITORY_NAME`       | Artifact Registry repo name    |\n| `WIF_PROVIDER_ID`           | Workload Identity Provider ID  |\n| `GCP_SERVICE_ACCOUNT_EMAIL` | Service account email          |\n\n### Enable Cloud Run Deployment\n\n\u003e [!IMPORTANT]\n\u003e In `.github/workflows/deploy.yml`, ensure the `deploy-cloud-run` job is **uncommented** and `deploy-vps` is *\n*commented out**.\n\n## Step 3: Deploy\n\n```bash\n# Push to trigger deployment\ngit add .\ngit commit -m \"Configure Cloud Run deployment\"\ngit push origin main\n```\n\n\u003e [!TIP]\n\u003e Your app will be available at the Cloud Run URL shown in the GitHub Actions output! The URL format is typically:\n\u003e `https://SERVICE-NAME-HASH-REGION.a.run.app`\n\n### Cloud Run Management\n\n```bash\n# View service details\ngcloud run services describe fastapi-docker-traefik --region=us-central1\n\n# View logs\ngcloud run services logs tail fastapi-docker-traefik --region=us-central1\n\n# Update service manually\ngcloud run deploy fastapi-docker-traefik \\\n  --image=us-central1-docker.pkg.dev/PROJECT_ID/REPO/fastapi-docker-traefik:latest \\\n  --region=us-central1\n```\n\n---\n\n## 🧪 Local Development\n\n### Setup Development Environment\n\n\u003e [!TIP]\n\u003e Using `uv` provides significantly faster dependency resolution and installation compared to pip.\n\n```bash\n# Install uv (fast Python package manager)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install dependencies\nuv sync --all-extras --dev\n\n# Run tests\nuv run ruff check\nuv run pytest\n\n# Run locally\nuv run fastapi dev app/main.py\n```\n\n### Docker Development\n\n```bash\n# Run with Docker Compose (VPS-like environment)\ndocker compose up --build\n\n# Run single container\ndocker build -t fastapi-app .\ndocker run -p 8080:8080 fastapi-app\n```\n\n\u003e [!NOTE]\n\u003e The local development server runs on port 8000, while the Docker container runs on port 8080.\n\n---\n\n## 🔧 Customization\n\n### Modify Your FastAPI App\n\nEdit `app/main.py` to build your application. The template includes:\n\n```python\nfrom fastapi import FastAPI\n\napp = FastAPI(title=\"Your App Name\")\n\n\n@app.get(\"/\")\nasync def root():\n    return {\"message\": \"Hello World\"}\n```\n\n\u003e [!TIP]\n\u003e Add your API routes, middleware, and dependencies to this file. Consider organizing larger applications into multiple\n\u003e modules.\n\n### Environment Variables\n\nBoth deployment paths support environment variables:\n\n\u003e [!IMPORTANT]\n\u003e Never commit sensitive environment variables to your repository. Use GitHub Secrets for sensitive data.\n\n```env\n# .env file (VPS) or Cloud Run environment variables\nDATABASE_URL=postgresql://...\nREDIS_URL=redis://...\nSECRET_KEY=your-secret-key\n```\n\n### Custom Domains\n\n**VPS**: Configure DNS A record → automatic HTTPS via Let's Encrypt\n\n**Cloud Run**: Use Cloud Run domain mapping for custom domains\n\n\u003e [!NOTE]\n\u003e Custom domains on Cloud Run require domain verification and may incur additional charges.\n\n---\n\n## 🚨 Troubleshooting\n\n### VPS Issues\n\n\u003e [!WARNING]\n\u003e If SSL certificate generation fails, check that your domain's DNS records are correctly configured and propagated.\n\n```bash\n# Check Traefik logs\ndocker compose logs traefik\n\n# Check SSL certificates\ndocker compose exec traefik cat /etc/traefik/acme/acme.json\n\n# Verify DNS resolution\ndig yourdomain.com\n```\n\n\u003e [!TIP]\n\u003e Common issues:\n\u003e - DNS not propagated (wait 24-48 hours after DNS changes)\n\u003e - Firewall blocking ports 80/443\n\u003e - Incorrect domain name in configuration\n\n### Cloud Run Issues\n\n```bash\n# Check deployment status\ngcloud run services list\n\n# View recent logs\ngcloud run services logs tail SERVICE_NAME --region=REGION\n\n# Check IAM permissions\ngcloud projects get-iam-policy PROJECT_ID\n```\n\n\u003e [!CAUTION]\n\u003e If deployment fails, check:\n\u003e - GitHub Actions logs for detailed error messages\n\u003e - Service account permissions in GCP IAM\n\u003e - Artifact Registry repository accessibility\n\n---\n\n## 🙌 Acknowledgements\n\n* Inspired by [`dreamsofcode-io/guestbook`](https://github.com/dreamsofcode-io/guestbook)\n* Uses [`uv`](https://github.com/astral-sh/uv) for dependency management\n* Built by [@atick-faisal](https://github.com/atick-faisal)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/footers/gray0_ctp_on_line.svg?sanitize=true\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://sites.google.com/view/mchowdhury\" target=\"_blank\"\u003eQatar University Machine Learning Group\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/atick-faisal/fastapi-docker-traefik/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/atick-faisal/fastapi-docker-traefik?style=for-the-badge\u0026colorA=363a4f\u0026colorB=b7bdf8\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatick-faisal%2Ffastapi-docker-traefik","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatick-faisal%2Ffastapi-docker-traefik","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatick-faisal%2Ffastapi-docker-traefik/lists"}