{"id":28758940,"url":"https://github.com/mmmylnikov/django-ninja-api-template","last_synced_at":"2026-04-13T06:03:43.978Z","repository":{"id":298303495,"uuid":"999510243","full_name":"mmmylnikov/django-ninja-api-template","owner":"mmmylnikov","description":"Flexible Django Ninja API template with PostgreSQL full-text search and gRPC integration examples.","archived":false,"fork":false,"pushed_at":"2025-06-10T11:23:31.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-10T12:30:34.725Z","etag":null,"topics":["api","celery","django","django-ninja","docker","grpc","jwt","microservice","openapi","postgresql","rest-api","template","vector-search"],"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/mmmylnikov.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,"zenodo":null}},"created_at":"2025-06-10T11:08:39.000Z","updated_at":"2025-06-10T11:25:12.000Z","dependencies_parsed_at":"2025-06-10T12:33:10.250Z","dependency_job_id":"4cd9e4d2-7573-4d88-af1d-4f2a9d47bb09","html_url":"https://github.com/mmmylnikov/django-ninja-api-template","commit_stats":null,"previous_names":["mmmylnikov/django-ninja-api-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mmmylnikov/django-ninja-api-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmmylnikov%2Fdjango-ninja-api-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmmylnikov%2Fdjango-ninja-api-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmmylnikov%2Fdjango-ninja-api-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmmylnikov%2Fdjango-ninja-api-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmmylnikov","download_url":"https://codeload.github.com/mmmylnikov/django-ninja-api-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmmylnikov%2Fdjango-ninja-api-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260294416,"owners_count":22987618,"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","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":["api","celery","django","django-ninja","docker","grpc","jwt","microservice","openapi","postgresql","rest-api","template","vector-search"],"created_at":"2025-06-17T05:00:37.499Z","updated_at":"2026-04-13T06:03:43.933Z","avatar_url":"https://github.com/mmmylnikov.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django Ninja API Template\n\n[![CI](https://github.com/mmmylnikov/django-ninja-api-template/actions/workflows/ci.yml/badge.svg)](https://github.com/mmmylnikov/django-ninja-api-template/actions/workflows/ci.yml)\n![Django](https://img.shields.io/badge/Django-092E20?logo=django\u0026logoColor=white)\n![Django Ninja](https://img.shields.io/badge/Django_Ninja-F55247?logo=ninja\u0026logoColor=white)\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL-316192?logo=postgresql\u0026logoColor=white)\n![gRPC](https://img.shields.io/badge/gRPC-244C5A?logo=grpc\u0026logoColor=white)\n![Celery](https://img.shields.io/badge/Celery-37814A?logo=celery\u0026logoColor=white)\n![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker\u0026logoColor=white)\n![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-2088FF?logo=github-actions\u0026logoColor=white)\n[![wemake-python-styleguide](https://img.shields.io/badge/style-wemake-000000.svg)](https://github.com/wemake-services/wemake-python-styleguide)\n\n\nA flexible project template for building modern Django Ninja API services with\nJWT authentication, gRPC integration, and vector (full-text) search support in\nPostgreSQL. This template is ideal for rapid prototyping or as a foundation\nfor scalable backend systems.\n\n---\n\n## Features\n\n- **Django Ninja** framework with fast OpenAPI support\n- **JWT authentication** (login, refresh)\n- **gRPC integration** (sample notification server included)\n- **Vector and full-text search** in PostgreSQL\n- **Docker Compose** setup for development (database, valkey, notify server, \n    backend, celery worker/beat/flower)\n- **Celery integration** (background tasks, scheduling, monitoring)\n- **Custom management commands** (e.g., sample user data)\n- **Clean project structure** with `api.py`, `schemas.py`, `services.py`\n    in each app\n- **Ready-to-use user roles** and event-related entities\n\n---\n\n## Stack \u0026 Services\n\nThis project uses Docker Compose for easy local development. The following\nservices are available:\n\n- **database**: PostgreSQL 14 (with vector and full-text search enabled)\n- **valkey**: Lightning-fast in-memory key-value store (Valkey)\n- **backend**: Django app running on port `8080`\n- **celery_worker**: Celery worker for async/background tasks\n- **celery_beat**: Celery Beat for scheduled tasks\n- **celery_flower**: Flower monitoring UI (available at port `5555`)\n- **notification-server**: Test gRPC notification server\n\n---\n\n## Quickstart\n\n1. **Clone the repository and start services:**\n    ```sh\n    docker compose up --build\n    ```\n\n2. **Perform the necessary migrations:**\n    ```sh\n    docker compose exec backend python manage.py migrate\n    ```\n\n3. **Optional: initialize test data (admin, organizer, visitor):**\n    ```sh\n    docker compose exec backend python manage.py initdata\n    ```\n\n4. **Access API documentation (OpenAPI/Swagger):**\n    - http://localhost:8080/api/docs\n\n5. **Access Flower UI:**\n    - http://localhost:5555\n\n---\n\n## Authentication\n\n- JWT is used for authentication.\n- Register a user and get a token for further requests.\n- Use the \"Authorization: Bearer \u003ctoken\u003e\" header.\n\n---\n\n## Example Endpoints\n\n| Method | URL                            | Description            |\n|--------|--------------------------------|------------------------|\n| POST   | /api/users/register            | Register User          |\n| POST   | /api/auth/login                | Login (JWT)            |\n| POST   | /api/auth/token/refresh        | Token Refresh          |\n| GET    | /api/events/                   | List Events            |\n| POST   | /api/events/                   | Create Event           |\n| GET    | /api/events/upcoming/          | User Upcoming Events   |\n| GET    | /api/events/{event_id}/        | Get Event Details      |\n| DELETE | /api/events/{event_id}/        | Delete Event           |\n| PATCH  | /api/events/{event_id}/status/ | Update Event Status    |\n| POST   | /api/events/{event_id}/book/   | Book Event             |\n| DELETE | /api/events/{event_id}/book/   | Cancel Booking         |\n\n---\n\n## Notifications\n\n- A sample gRPC notification server is included and receives notification\n  messages.\n- Easily integrate real notification services by changing the gRPC server logic.\n\n---\n\n## Management Commands\n\n- `python manage.py initdata` — creates test users: **admin**, **organizer**, **visitor**.\n\n---\n\n## Configuration\n\nThe project uses environment variables for configuration. Create a `.env` file \nin the project root with the following variables:\n\n```txt\nDEBUG=True\nDEBUG_HOST=127.0.0.1\nDEBUG_PORT=8080\n\nLANGUAGE_CODE=ru-RU\nTIME_ZONE=Asia/Yekaterinburg\n\nSECRET_KEY=your-secret-key\nALLOWED_HOSTS=127.0.0.1,localhost\n\nDB_ENGINE=django.db.backends.postgresql\nDB_NAME=django_db\nDB_USER=django_user\nDB_PASSWORD=django_password\nDB_PASSWORD_ROOT=django_password_root\nDB_HOST=database\nDB_PORT=5432\n\nCELERY_BROKER_URL=redis://valkey:6379/0\nCELERY_RESULT_BACKEND=django-db\n\nGRPC_SERVER_HOST=notification-server\nGRPC_SERVER_PORT=50051\n```\n\n## Development Setup\n\n### Prerequisites\n\n- Docker and Docker Compose\n- uv\n- Python 3.13+\n- Make (optional, for running Makefile commands)\n\n### Local Development\n\n1. **Clone the repository:**\n```sh\ngit clone https://github.com/mmmylnikov/django-ninja-api-template.git\ncd django-ninja-api-template\n```\n\n2. Create a virtual environment:\n\n```sh\nuv sync\n```\n\n### Makefile Commands\n\nThe project includes a Makefile with various commands to streamline development:\n\n#### Code Quality\n```sh\n# Check WPS coding style issues\nuv run make style_wps\n\n# Run Ruff linter\nuv run make style_ruff\n\n# Format code with Ruff\nuv run make format_ruff\n\n# Run all style checks and formatting\nuv run make style\n\n# Run type checking with mypy\nuv run make types\n\n# Run all checks (style + type checking)\nuv run make check\n```\n\n#### Project Management\n\n```sh\n# Run Django development server\nuv run make debug\n\n# Run migrations\nuv run make migrate\n\n# Initialize test data\nuv run make initdata\n```\n\n#### Celery Management\n\n```sh\n# Run Celery worker\nuv run make celery\n\n# Run Celery Beat scheduler\nuv run make celery_beat\n\n# Run Celery Flower monitoring\nuv run make celery_flower\n```\n\n#### gRPC\n\n```sh\n# Generate Python code from Protocol Buffer definition\nuv run make notify_build_proto\n```\n\n#### CI/CD\n\n```sh\n# Run locally CI Workflow\nuv run make actci\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmmylnikov%2Fdjango-ninja-api-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmmylnikov%2Fdjango-ninja-api-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmmylnikov%2Fdjango-ninja-api-template/lists"}