{"id":31585025,"url":"https://github.com/mugubr/django_base","last_synced_at":"2025-10-08T12:13:10.907Z","repository":{"id":317967211,"uuid":"1068201792","full_name":"mugubr/django_base","owner":"mugubr","description":"🚀 A modern, production-ready Django boilerplate. Fully containerized with Docker, Nginx, Gunicorn, PostgreSQL, CI/CD, and observability.","archived":false,"fork":false,"pushed_at":"2025-10-04T06:31:48.000Z","size":152,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-04T08:23:01.863Z","etag":null,"topics":["cicd","django","django-q","docker","docker-compose","gunicorn","nginx","postgres","python","ruff","uv"],"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/mugubr.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-10-02T02:23:55.000Z","updated_at":"2025-10-03T17:17:23.000Z","dependencies_parsed_at":"2025-10-04T08:23:07.697Z","dependency_job_id":"a35aaad2-6291-43ba-ad44-3bf3f0b0f2eb","html_url":"https://github.com/mugubr/django_base","commit_stats":null,"previous_names":["mugubr/django_base"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mugubr/django_base","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mugubr%2Fdjango_base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mugubr%2Fdjango_base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mugubr%2Fdjango_base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mugubr%2Fdjango_base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mugubr","download_url":"https://codeload.github.com/mugubr/django_base/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mugubr%2Fdjango_base/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278547764,"owners_count":26004772,"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-10-05T02:00:06.059Z","response_time":54,"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":["cicd","django","django-q","docker","docker-compose","gunicorn","nginx","postgres","python","ruff","uv"],"created_at":"2025-10-06T01:26:19.910Z","updated_at":"2025-10-06T01:26:29.077Z","avatar_url":"https://github.com/mugubr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django Base (django_base) 🚀\n\n🇬🇧 / 🇺🇸\n## English\n\nThis is a modern base project for Django development, fully configured to run in a robust and professional Docker environment. The structure is designed to be efficient, scalable, and easy to maintain, utilizing the best practices and tools in the ecosystem.\n\n### 🛠️ Tech Stack\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Django-092E20?style=for-the-badge\u0026logo=django\u0026logoColor=white\" alt=\"Django\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/DRF-A30000?style=for-the-badge\u0026logo=django-rest-framework\u0026logoColor=white\" alt=\"Django REST Framework\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge\u0026logo=postgresql\u0026logoColor=white\" alt=\"PostgreSQL\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Nginx-009639?style=for-the-badge\u0026logo=nginx\u0026logoColor=white\" alt=\"Nginx\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Gunicorn-499848?style=for-the-badge\u0026logo=gunicorn\u0026logoColor=white\" alt=\"Gunicorn\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white\" alt=\"Docker\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Ruff-D7B092?style=for-the-badge\u0026logo=ruff\u0026logoColor=black\" alt=\"Ruff\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Prometheus-E6522C?style=for-the-badge\u0026logo=prometheus\u0026logoColor=white\" alt=\"Prometheus\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Grafana-F46800?style=for-the-badge\u0026logo=grafana\u0026logoColor=white\" alt=\"Grafana\"\u003e\n\u003c/div\u003e\n\n-   **Web Server:** Nginx\n-   **Application Server:** Gunicorn\n-   **Backend:** Django, Django REST Framework\n-   **Database:** PostgreSQL\n-   **Package Manager:** `uv`\n-   **Background Tasks:** Django Q2 (`django-q2`)\n-   **API Communication:** CORS (`django-cors-headers`)\n-   **Containerization:** Docker \u0026 Docker Compose\n-   **Code Quality:** `Ruff` \u0026 `pre-commit`\n-   **Testing:** `django.test` with `coverage`\n-   **Observability:** `Prometheus` \u0026 `Grafana`\n-   **Environment Variables:** `python-decouple`\n-   **Development Tools:** `django-extensions` with `watchdog` for hot-reloading.\n\n### 🏁 Running the Project (Docker)\n\n#### 💻 Development Mode (`dev` profile)\n\nThis mode is for active development. It uses Django's development server with hot-reloading and provides detailed logs.\n\n1.  **First-Time Setup:**\n    ```bash\n    # Clone the repo and enter the directory\n    git clone \u003cyour-repository-url\u003e \u0026\u0026 cd django_base\n    \n    # Create the environment file\n    cp .env.example .env\n    \n    # Build the images\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev build\n    \n    # Run database migrations (using 'run' for a temporary container)\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml run --rm web python manage.py migrate\n    \n    # Create a superuser\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml run --rm web python manage.py createsuperuser\n    ```\n\n2.  **To Start the Development Server:**\n    *This command will attach to your terminal and show live logs. Press `Ctrl + C` to stop.*\n    ```bash\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev up\n    ```\n\n#### 🚀 Production Mode (`prod` profile)\n\nThis mode runs the production-like stack with Nginx and Gunicorn.\n\n1.  **To Start the Production Stack:**\n    ```bash\n    docker-compose --profile prod up -d --build\n    ```\n\n2.  **Required Commands (after starting):**\n    ```bash\n    # Run migrations\n    docker-compose --profile prod exec web python manage.py migrate\n    # Collect static files for Nginx\n    docker-compose --profile prod exec web python manage.py collectstatic --no-input\n    ```\n\nThe application will be available at `http://localhost:8000` with hot-reload enabled.\n\nAfter these steps, your environment will be running\n-   **Application:** `http://localhost:8000`\n-   **Example API Endpoint:** `http://localhost:8000/api/v1/hello/`\n-   **Django Admin:** `http://localhost:8000/admin`\n-   **Prometheus:** `http://localhost:9090`\n-   **Grafana:** `http://localhost:3000` (login: `admin`/`admin`)\n\n---\n\n### 💻 Local Development (Without Docker)\n\n#### Prerequisites\n\n-   Python 3.11+\n-   A local PostgreSQL server running.\n-   `uv`, `pip`, or `poetry` installed.\n\n#### Steps\n\n1.  **Clone the repository and `cd` into it.**\n\n2.  **Set up the environment file (`.env`):**\n    Copy `.env.example` to `.env`. **Crucially, you must change `HOST=db` to `HOST=localhost`** so Django connects to your local PostgreSQL instance, not a Docker container.\n    ```bash\n    cp .env.example .env\n    # Now edit .env and change HOST=db to HOST=localhost\n    ```\n\n3.  **Install dependencies (choose one method):**\n\n    * **Using `uv` (Recommended):**\n        ```bash\n        # Create a virtual environment\n        uv venv\n        # Activate it (macOS/Linux)\n        source .venv/bin/activate\n        # Activate it (Windows PowerShell)\n        .venv\\Scripts\\Activate.ps1\n        # or Windows (Command Prompt)\n        .venv\\Scripts\\activate.bat\n        # Install all dependencies\n        uv sync --dev\n        ```\n\n    * **Using `pip`:**\n        ```bash\n        # Create a virtual environment\n        python -m venv .venv\n        # Activate it (macOS/Linux)\n        source .venv/bin/activate\n        # Activate it (Windows PowerShell)\n        .venv\\Scripts\\Activate.ps1\n        # or Windows (Command Prompt)\n        .venv\\Scripts\\activate.bat\n        # Install all dependencies from requirements.txt\n        pip install -r requirements.txt\n        ```\n\n    * **Using `Poetry`:**\n        ```bash\n        # Install all dependencies (Poetry manages the venv automatically)\n        poetry install\n        # To activate the shell\n        poetry shell\n        ```\n\n4.  **Run Migrations and the Server:**\n    *(Ensure your virtual environment is activated if using `uv` or `pip`)*\n    ```bash\n    # Run migrations\n    python manage.py migrate\n    # Run the development server\n    python manage.py runserver_plus\n    ```\n\n---\n\n### 📖 Development Workflow\n\n#### How to Add a New Library\n\nThe `pyproject.toml` file is the source of truth for dependencies. Use the CLI commands of your package manager to add new libraries, as this will update the file automatically.\n\n**With Docker:**\n\n1.  **Run the install command inside the `web` container:**\n    ```bash\n    # For a production dependency\n    docker-compose exec web uv add \"some-package\"\n\n    # For a development dependency (like a testing tool)\n    docker-compose exec web uv add \"some-dev-package\" --dev\n    ```\n2.  **To make the change permanent in the image**, rebuild it after updating `pyproject.toml`:\n    ```bash\n    docker-compose build\n    ```\n\n**Locally (without Docker):**\n\n*(Ensure your virtual environment is activated)*\n\n* **Using `uv`:**\n    ```bash\n    # For a production dependency\n    uv add \"some-package\"\n\n    # For a development dependency\n    uv add \"some-dev-package\" --dev\n    ```\n* **Using `Poetry`:**\n    ```bash\n    # For a production dependency\n    poetry add \"some-package\"\n\n    # For a development dependency\n    poetry add \"some-dev-package\" --group dev\n    ```\n* **After Adding:** If your team uses `requirements.txt`, remember to regenerate it:\n    ```bash\n    uv pip freeze \u003e requirements.txt\n    ```\n\n#### How to Create a New App\n\n1.  Ensure your **development** environment is running.\n2.  Execute the `startapp` command:\n    ```bash\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml exec web python manage.py startapp my_new_app\n    ```\n3.  Move the new `my_new_app` folder from the project root into the `src/` directory.\n4.  Add `'my_new_app'` to `INSTALLED_APPS` in `src/django_base/settings.py`.\n5.  Create and configure the app's `urls.py`.\n\n---\n\n### 🚀 Day-to-Day Commands (Docker)\n\n-   **Start the environment with live logs (Recommended for development):**\n    *Shows colored, hot-reloading logs in your terminal. To stop, press `Ctrl + C`.*\n    ```bash\n    docker-compose up\n    ```\n\n-   **Start the environment in the background:**\n    ```bash\n    docker-compose up -d\n    ```\n\n-   **Stop all services:**\n    ```bash\n    docker-compose down\n    ```\n\n-   **View logs (if running in the background):**\n    ```bash\n    docker-compose logs -f web\n    ```\n\n-   **Access the web container's shell:**\n    ```bash\n    docker-compose exec web bash\n    ```\n\n### ✅ Running Tests\n\n-   **Run tests and generate coverage data:**\n    ```bash\n    docker-compose exec web python -m coverage run manage.py test\n    ```\n\n-   **View the coverage report in the terminal:**\n    ```bash\n    docker-compose exec web python -m coverage report -m\n    ```\n\n-   **Generate an interactive HTML report (saved in the `htmlcov/` folder):**\n    ```bash\n    docker-compose exec web python -m coverage html\n    ```\n\n### ✨ Code Quality\n\n#### Ruff \u0026 Pre-commit\n\n`pre-commit` is configured to run `ruff` (formatter and linter) automatically before each commit, ensuring code consistency.\n\n-   **Activation (optional, but recommended):**\n    To enable this, install `pre-commit` on your local machine and run:\n    ```bash\n    pre-commit install\n    ```\n\n#### VSCode\n\nThe settings in `.vscode/settings.json` integrate `ruff` with the editor, automatically formatting your code on save.\n\n### ⁉️ Troubleshooting\n\nIf the environment behaves unexpectedly, a corrupted Docker cache is the most likely cause. Follow these \"deep clean\" steps:\n\n1.  **Stop and remove containers and networks:**\n    ```bash\n    docker-compose down\n    ```\n2.  **Prune the build cache:**\n    ```bash\n    docker builder prune\n    ```\n3.  **Rebuild the images from scratch:**\n    ```bash\n    docker-compose build --no-cache\n    ```\n4.  **Start the services again:**\n    ```bash\n    docker-compose up -d\n    ```\n\n---\n\n🇧🇷\n## Português (Brasil)\n\nEste é um projeto base moderno para desenvolvimento com Django, totalmente configurado para rodar em um ambiente Docker robusto e profissional. A estrutura foi projetada para ser eficiente, escalável e fácil de manter, utilizando as melhores práticas e ferramentas do ecossistema.\n\n### 🛠️ Tecnologias Utilizadas\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Django-092E20?style=for-the-badge\u0026logo=django\u0026logoColor=white\" alt=\"Django\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/DRF-A30000?style=for-the-badge\u0026logo=django-rest-framework\u0026logoColor=white\" alt=\"Django REST Framework\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge\u0026logo=postgresql\u0026logoColor=white\" alt=\"PostgreSQL\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Nginx-009639?style=for-the-badge\u0026logo=nginx\u0026logoColor=white\" alt=\"Nginx\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Gunicorn-499848?style=for-the-badge\u0026logo=gunicorn\u0026logoColor=white\" alt=\"Gunicorn\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white\" alt=\"Docker\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Ruff-D7B092?style=for-the-badge\u0026logo=ruff\u0026logoColor=black\" alt=\"Ruff\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Prometheus-E6522C?style=for-the-badge\u0026logo=prometheus\u0026logoColor=white\" alt=\"Prometheus\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Grafana-F46800?style=for-the-badge\u0026logo=grafana\u0026logoColor=white\" alt=\"Grafana\"\u003e\n\u003c/div\u003e\n\n-   **Servidor Web:** Nginx\n-   **Servidor de Aplicação:** Gunicorn\n-   **Backend:** Django, Django REST Framework\n-   **Banco de Dados:** PostgreSQL\n-   **Gerenciador de Pacotes:** `uv`\n-   **Tarefas em Background:** Django Q2 (`django-q2`)\n-   **Comunicação de API:** CORS (`django-cors-headers`)\n-   **Containerização:** Docker \u0026 Docker Compose\n-   **Qualidade de Código:** `Ruff` e `pre-commit`\n-   **Testes:** `django.test` com `coverage`\n-   **Observabilidade:** `Prometheus` e `Grafana`\n-   **Variáveis de Ambiente:** `python-decouple`\n-   **Ferramentas de Desenvolvimento:** `django-extensions` com `watchdog` para hot-reloading.\n\n### 🏁 Executando o Projeto (Docker)\n\n#### 💻 Modo de Desenvolvimento (perfil `dev`)\n\nEste modo é para o desenvolvimento ativo. Ele usa o servidor de desenvolvimento do Django com hot-reloading e logs detalhados.\n\n1.  **Setup da Primeira Vez:**\n    ```bash\n    # Clone o repositório e entre na pasta\n    git clone \u003curl-do-seu-repositorio\u003e \u0026\u0026 cd django_base\n    \n    # Crie o arquivo de ambiente\n    cp .env.example .env\n    \n    # Construa as imagens\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev build\n    \n    # Rode as migrações (usando 'run' para um container temporário)\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml run --rm web python manage.py migrate\n    \n    # Crie um superusuário\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml run --rm web python manage.py createsuperuser\n    ```\n\n2.  **Para Iniciar o Servidor de Desenvolvimento:**\n    *Este comando vai \"prender\" seu terminal e mostrar os logs ao vivo. Pressione `Ctrl + C` para parar.*\n    ```bash\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml --profile dev up\n    ```\n\n#### 🚀 Modo de Produção (perfil `prod`)\n\nEste modo executa a stack de produção com Nginx e Gunicorn.\n\n1.  **Para Iniciar a Stack de Produção:**\n    ```bash\n    docker-compose --profile prod up -d --build\n    ```\n\n2.  **Comandos Necessários (após iniciar):**\n    ```bash\n    # Rodar migrações\n    docker-compose --profile prod exec web python manage.py migrate\n    # Coletar arquivos estáticos para o Nginx\n    docker-compose --profile prod exec web python manage.py collectstatic --no-input\n    ```\n\nApós esses passos, seu ambiente estará no ar!\n-   **Aplicação:** `http://localhost:8000`\n-   **Endpoint de API de Exemplo:** `http://localhost:8000/api/v1/hello/`\n-   **Admin do Django:** `http://localhost:8000/admin`\n-   **Prometheus:** `http://localhost:9090`\n-   **Grafana:** `http://localhost:3000` (login: `admin`/`admin`)\n---\n\n### 💻 Desenvolvimento Local (Sem Docker)\n\n#### Pré-requisitos\n\n-   Python 3.11+\n-   Um servidor PostgreSQL rodando localmente.\n-   `uv`, `pip`, ou `poetry` instalados.\n\n#### Passos\n\n1.  **Clone o repositório e entre na pasta.**\n\n2.  **Configure o arquivo de ambiente (`.env`):**\n    Copie o `.env.example` para `.env`. **É crucial que você altere `HOST=db` para `HOST=localhost`**, para que o Django se conecte à sua instância local do PostgreSQL, e não a um contêiner.\n    ```bash\n    cp .env.example .env\n    # Agora, edite o arquivo .env e mude HOST=db para HOST=localhost\n    ```\n\n3.  **Instale as dependências (escolha um método):**\n\n    * **Usando `uv` (Recomendado):**\n        ```bash\n        # Crie o ambiente virtual\n        uv venv\n        # Ative o ambiente (macOS/Linux)\n        source .venv/bin/activate\n        # Ative o ambiente (Windows PowerShell)\n        .venv\\Scripts\\Activate.ps1\n        # ou no Windows (Command Prompt)\n        .venv\\Scripts\\activate.bat\n        # Instale todas as dependências\n        uv sync --dev\n        ```\n\n    * **Usando `pip`:**\n        ```bash\n        # Crie o ambiente virtual\n        python -m venv .venv\n        # Ative o ambiente (macOS/Linux)\n        source .venv/bin/activate\n        # Ative o ambiente (Windows PowerShell)\n        .venv\\Scripts\\Activate.ps1\n        # ou no Windows (Command Prompt)\n        .venv\\Scripts\\activate.bat\n        # Instale as dependências a partir do requirements.txt\n        pip install -r requirements.txt\n        ```\n\n    * **Usando `Poetry`:**\n        ```bash\n        # Instala as dependências (o Poetry gerencia o ambiente virtual)\n        poetry install\n        # Para ativar o shell do ambiente\n        poetry shell\n        ```\n\n4.  **Execute as Migrações e o Servidor:**\n    *(Garanta que seu ambiente virtual esteja ativado se usar `uv` ou `pip`)*\n    ```bash\n    # Rode as migrações\n    python manage.py migrate\n    # Rode o servidor de desenvolvimento\n    python manage.py runserver_plus\n    ```\n\n---\n\n### 📖 Workflow de Desenvolvimento\n\n#### Como Adicionar uma Nova Biblioteca\n\nO arquivo `pyproject.toml` é a fonte da verdade para as dependências. Use os comandos CLI do seu gerenciador de pacotes para adicionar novas bibliotecas, pois isso atualizará o arquivo automaticamente.\n\n**Com Docker:**\n\n1.  **Execute o comando de instalação dentro do container `web`:**\n    ```bash\n    # Para uma dependência de produção\n    docker-compose exec web uv add \"nome-do-pacote\"\n\n    # Para uma dependência de desenvolvimento (ex: ferramenta de teste)\n    docker-compose exec web uv add \"pacote-de-dev\" --dev\n    ```\n2.  **Para tornar a mudança permanente na imagem**, reconstrua-a após atualizar o `pyproject.toml`:\n    ```bash\n    docker-compose build\n    ```\n\n**Localmente (sem Docker):**\n\n*(Garanta que seu ambiente virtual esteja ativado)*\n\n* **Usando `uv`:**\n    ```bash\n    # Para uma dependência de produção\n    uv add \"nome-do-pacote\"\n\n    # Para uma dependência de desenvolvimento\n    uv add \"nome-do-pacote\" --dev\n    ```\n* **Usando `Poetry`:**\n    ```bash\n    # Para uma dependência de produção\n    poetry add \"nome-do-pacote\"\n\n    # Para uma dependência de desenvolvimento\n    poetry add \"pacote-de-dev\" --group dev\n    ```\n* **Após Adicionar:** Se seu time utiliza `requirements.txt`, lembre-se de regerá-lo:\n    ```bash\n    uv pip freeze \u003e requirements.txt\n    ```\n\n#### Como Criar uma Nova App\n\n1.  **Garanta que seu ambiente de desenvolvimento esteja rodando.**\n2.  Execute o comando `startapp`:\n    ```bash\n    docker-compose -f docker-compose.yml -f docker-compose.dev.yml exec web python manage.py startapp meu_novo_app\n    ```\n3.  Mova a nova pasta `meu_novo_app` da raiz do projeto para dentro do diretório `src/`.\n4.  Adicione `'meu_novo_app'` à lista `INSTALLED_APPS` no arquivo `src/django_base/settings.py`.\n5.  Crie e configure o arquivo `urls.py` da sua nova app, e inclua-o no `urls.py` principal.\n---\n\n### 🚀 Comandos do Dia a Dia (Docker)\n\n-   **Iniciar o ambiente com logs ao vivo (Recomendado para desenvolver):**\n    *Mostra os logs coloridos e com hot-reload no seu terminal. Para parar, pressione `Ctrl + C`.*\n    ```bash\n    docker-compose up\n    ```\n\n-   **Iniciar o ambiente em segundo plano:**\n    ```bash\n    docker-compose up -d\n    ```\n\n-   **Parar todos os serviços:**\n    ```bash\n    docker-compose down\n    ```\n\n-   **Ver os logs (se estiver rodando em segundo plano):**\n    ```bash\n    docker-compose logs -f web\n    ```\n\n-   **Acessar o terminal (shell) do container web:**\n    ```bash\n    docker-compose exec web bash\n    ```\n\n### ✅ Executando Testes\n\n-   **Rodar os testes e gerar dados de cobertura:**\n    ```bash\n    docker-compose exec web python -m coverage run manage.py test\n    ```\n\n-   **Ver o relatório de cobertura no terminal:**\n    ```bash\n    docker-compose exec web python -m coverage report -m\n    ```\n\n-   **Gerar um relatório HTML interativo (salvo na pasta `htmlcov/`):**\n    ```bash\n    docker-compose exec web python -m coverage html\n    ```\n\n### ✨ Qualidade de Código\n\n#### Ruff \u0026 Pre-commit\n\nO `pre-commit` está configurado para rodar o `ruff` (formatador e linter) automaticamente antes de cada commit, garantindo a consistência do código.\n\n-   **Ativação (opcional, mas recomendado):**\n    Para habilitar, instale `pre-commit` na sua máquina local e rode:\n    ```bash\n    pre-commit install\n    ```\n\n#### VSCode\n\nAs configurações em `.vscode/settings.json` integram o `ruff` ao editor, formatando seu código automaticamente ao salvar.\n\n### ⁉️ Solução de Problemas (Troubleshooting)\n\nSe o ambiente se comportar de forma estranha, um cache corrompido do Docker é a causa mais provável. Siga os passos de \"limpeza profunda\":\n\n1.  **Pare e remova contêineres e redes:**\n    ```bash\n    docker-compose down\n    ```\n2.  **Limpe o cache de build:**\n    ```bash\n    docker builder prune\n    ```\n3.  **Reconstrua as imagens do zero:**\n    ```bash\n    docker-compose build --no-cache\n    ```\n4.  **Inicie os serviços novamente:**\n    ```bash\n    docker-compose up -d\n    ```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmugubr%2Fdjango_base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmugubr%2Fdjango_base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmugubr%2Fdjango_base/lists"}