{"id":26695277,"url":"https://github.com/itszcx/fastapi-template","last_synced_at":"2026-04-19T13:32:10.949Z","repository":{"id":274343818,"uuid":"859917125","full_name":"ItsZcx/FastAPI-Template","owner":"ItsZcx","description":"FastAPI template that integrates Poetry, Alembic, SQLAlchemy, dotenv (Pydantic), Docker, and PostgreSQL.","archived":false,"fork":false,"pushed_at":"2025-01-26T17:47:36.000Z","size":91,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-26T19:18:16.204Z","etag":null,"topics":["alembic","docker","dotenv","fastapi","poetry","postgresql","sqalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","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/ItsZcx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-09-19T13:58:00.000Z","updated_at":"2025-03-12T15:14:58.000Z","dependencies_parsed_at":"2025-01-26T18:43:36.043Z","dependency_job_id":null,"html_url":"https://github.com/ItsZcx/FastAPI-Template","commit_stats":null,"previous_names":["itszcx/fastapi-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/ItsZcx/FastAPI-Template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsZcx%2FFastAPI-Template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsZcx%2FFastAPI-Template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsZcx%2FFastAPI-Template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsZcx%2FFastAPI-Template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ItsZcx","download_url":"https://codeload.github.com/ItsZcx/FastAPI-Template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ItsZcx%2FFastAPI-Template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32009111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"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":["alembic","docker","dotenv","fastapi","poetry","postgresql","sqalchemy"],"created_at":"2025-03-26T19:18:22.048Z","updated_at":"2026-04-19T13:32:10.930Z","avatar_url":"https://github.com/ItsZcx.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI Template\nA FastAPI template that integrates Poetry, Alembic, SQLAlchemy, dotenv (Pydantic), Docker, and PostgreSQL for a fully functional API setup.\n\nDocker is set up to run both a FastAPI and PostgreSQL container.\n\nAlembic files are included as references to help you understand how to modify them. However, as noted in the \"Setup\" section, you should remove and reinitialize these files before starting your own API project.\n\n## Table of Contents\n- [Project Structure](#project-structure)\n- [Template Setup](#template-setup)\n    - [1. Install Dependencies with Poetry](#1-install-dependencies-with-poetry)\n    - [2. Set Up Environment Variables with dotenv](#2-set-up-environment-variables-with-dotenv)\n    - [3. Run the Template with Docker](#3-run-the-template-with-docker)\n    - [4. Set Up Alembic Database Migrations](#4-set-up-alembic-database-migrations)\n\n\n\n## Project Structure\nThis project strucure is based on [project-structure-consistent--predictable](https://github.com/zhanymkanov/fastapi-best-practices#1-project-structure-consistent--predictable) by zhanymkanov. It has been modified to use poetry and docker instead of venv.\n\n```\nfastapi-template\n├── alembic/\n├── src\n│   ├── auth               # package\n│   │   ├── config.py        # local configs\n│   │   ├── dependencies.py  # specific auth router dependencies\n│   │   ├── exceptions.py    # package-specific errors\n│   │   ├── models.py        # database models\n│   │   ├── router.py        # auth router with endpoints\n│   │   ├── schemas.py       # pydantic models\n│   │   ├── service.py       # package-specific business logic\n│   │   └── utils.py         # any other non-business logic functions\n│   ├── aws\n│   │   ├── client.py        # client model for external service communication\n│   │   ├── config.py\n│   │   ├── exceptions.py\n│   │   ├── schemas.py\n│   │   └── utils.py\n│   └── package            # copy paste package\n│   │   ├── config.py\n│   │   ├── dependencies.py\n│   │   ├── exceptions.py\n│   │   ├── models.py\n│   │   ├── router.py\n│   │   ├── schemas.py\n│   │   ├── service.py\n│   │   └── utils.py\n│   ├── __init__.py\n│   ├── config.py            # global configs (dotenv, etc)\n│   ├── models.py            # global database models\n│   ├── exceptions.py        # global exceptions\n│   ├── pagination.py        # global module e.g. pagination\n│   ├── database.py          # database connection related stuff\n│   └── main.py\n├── tests/\n│   ├── auth\n│   ├── aws\n│   └── posts\n├── .env.example             # Variables used/needed in this .env\n├── .gitignore\n├── alembic.ini\n├── compose.yaml\n├── Dockerfile\n├── LICENSE\n├── poetry.lock\n├── pyproject.toml\n└── README.md\n```\n\n1. Store all domain directories inside `src` folder\n   1. `src/` - highest level of an app, contains common models, configs, and constants, etc.\n   2. `src/main.py` - root of the project, which inits the FastAPI app\n\n2. Each package has its own router, schemas, models, etc.\n   1. `config.py` - e.g. specific env vars\n   2. `dependencies.py` - router dependencies\n   3. `exceptions.py` - module specific exceptions, e.g. `PostNotFound`, `InvalidUserData`\n   4. `models.py` - for database models\n   5. `router.py` - is a core of each module with all the endpoints\n   6. `schemas.py` - for pydantic models\n   7. `service.py` - module specific business logic\n   8. `utils.py` - non-business logic functions, e.g. response normalization, data enrichment, etc.\n\n3. When package requires services or dependencies or configs from other packages - import them with an explicit module name\n```python\nfrom src.auth import config as auth_config\nfrom src.notifications import service as notification_service\nfrom src.posts.config import ErrorCode as PostsErrorCode  # in case we have Standard ErrorCode in config module of each package\n```\n\n## Template Setup\n\n### 1. Install Dependencies with Poetry\nEnsure that [Poetry](https://python-poetry.org) is installed. If you plan to use Docker and don't require IDE support for package management, you can skip this step.\n\n1. Update project dependencies, this will also create a virtualenv and install them. (100% they are outdated):\n   ```bash\n   poetry update\n   ```\n\n2. To add or update a package:\n   ```bash\n   poetry add \u003cpackage-name\u003e\n   ```\n   or for development dependencies:\n   ```bash\n   poetry add --group=dev \u003cpackage-name\u003e\n   ```\n\n### 2. Set Up Environment Variables with dotenv\nEnvironment variables are handled via a `.env` file. The `.env.example` file contains the essential variables required to run this project out of the box.\n\n1. Create a `.env` file at the project root:\n   ```bash\n   touch .env\n   ```\n\n2. Add your environment-specific variables:\n   ```bash\n    DB_URL=postgresql://postgres:1234@fastapi-postgres:5432/postgres\n    ALEMBIC_DB_URL=postgresql://postgres:1234@localhost:5432/postgresn\n   ```\n\n\nThe `.env` file is used by the `pydantic-settings` package to load environment variables into the FastAPI application. To locate the PostgreSQL container's IP address, inspect the Docker network that is created.\n### 3. Run The Template with Docker\n1. Make sure [Docker](https://docs.docker.com/) is installed on your system.\n\n2. Build and run the Docker containers:\n   ```bash\n   docker compose up -d\n   ```\n\nThis will start both the FastAPI app and the PostgreSQL database as Docker containers.\n\n3. To stop the containers (add --volumes to remove persistent PostgeSQL data):\n   ```bash\n   docker-compose down\n   ```\n\n3. Checking logs:\n   ```bash\n   docker compose logs --follow -t\n   ```\n\n### 4. Set Up Alembic Database Migrations\n1. Remove alembic example:\n   ```bash\n   rm -rf alembic/ alembic.ini\n   ```\n2. Initialize Alembic (creates the alembic dir and alembic.ini):\n   ```bash\n   poetry run alembic init alembic\n   ```\n\n3. Configure the `alembic/env.py` file to use your `ALEMBIC_DB_URL` from `.env`:\n    ```python\n    # Set up ALEMBIC_DB_URL from .env file\n    import os\n    from dotenv import load_dotenv\n    load_dotenv()\n    ALEMBIC_DB_URL = os.getenv(\"ALEMBIC_DB_URL\")\n\n    # Set up sqlalchemy.url (alembic.ini) variable\n    config.set_main_option(\"sqlalchemy.url\", ALEMBIC_DB_URL)\n\n    # Import ALL the models from the app (even if unused)\n    from src.database import Base\n    from src.package.models import Todos\n    # ...\n\n    # Set target_metadata\n    target_metadata = Base.metadata\n    ```\n\n4. Create a new migration script (you can remove --autogenerate and create the change yourself):\n   ```bash\n   # DATABASE HAS TO BE RUNNING!\n   poetry run alembic revision --autogenerate -m \"description of changes\"\n   ```\n\n5. Apply the migrations:\n   ```bash\n   poetry run alembic upgrade {REVISION_ID}\n   ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitszcx%2Ffastapi-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitszcx%2Ffastapi-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitszcx%2Ffastapi-template/lists"}