Configuração moderna de desenvolvimento Django com uv e Docker

Configurar um ambiente web em Python muitas vezes envolve ferramentas legadas. Este guia apresenta uma abordagem simplificada usando Docker, Django, uv e Just. Esta configuração ignora pip, virtualenv e arquivos de requisitos, utilizando o uv para o gerenciamento de dependências e arquivos de bloqueio sem exigir ativação manual de ambiente. Ela também substitui Makefiles por Just para atalhos de comandos mais simples.

Inicializando o projeto com uv

Para começar, crie um novo projeto uv. Execute o seguinte comando no seu terminal para inicializar a estrutura de diretórios:

uv init --no-package django-project
cd django-project

Em seguida, instale django e psycopg para lidar com o framework web e a conectividade com o banco de dados PostgreSQL:

uv add "django==5.2.*" psycopg[binary]

Com os pacotes principais instalados, inicie a estrutura do seu novo projeto Django executando:

uv run django-admin startproject config .

Automatizando tarefas com Just e Docker

Em vez de depender de um Makefile tradicional, use um Justfile para gerenciar os comandos de desenvolvimento local. Crie um Justfile e adicione este código:

export UV_ENV_FILE := ".env"

manage := "uv run manage.py"

manage *args:
    @{{manage}} {{args}}

migrate *args:
    @{{manage}} migrate {{args}}

createsuperuser *args:
    @{{manage}} createsuperuser {{args}}

runserver:
    @{{manage}} runserver

Para gerenciar o contêiner do banco de dados, crie um arquivo compose.yaml na raiz do seu projeto e adicione estas linhas:

services:
  postgresql:
    image: postgres:18-alpine
    environment:
      POSTGRES_DB: django_project
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - 5432:5432
    volumes:
      - pgdata:/var/lib/postgresql

volumes:
  pgdata:

Inicie o seu serviço postgresql em segundo plano executando este comando:

docker compose up -d

Configurando as definições do banco de dados e executando migrações

Para conectar sua aplicação Django ao contêiner PostgreSQL, importe os e atualize o dicionário DATABASES no seu arquivo config/settings.py:

import os

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.getenv("DATABASE_NAME"),
        'USER': os.getenv("DATABASE_USER"),
        'PASSWORD': os.getenv("DATABASE_PASSWORD"),
        'HOST': os.getenv('DATABASE_HOST'),
        'PORT': os.getenv("DATABASE_PORT"),
    },
}

Em seguida, crie um arquivo .env no seu diretório raiz para armazenar as credenciais do banco de dados e os segredos do ambiente:

DATABASE_NAME=django_project
DATABASE_USER=postgres
DATABASE_PASSWORD=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432

Com seu ambiente configurado, faça as migrações iniciais do banco de dados usando o uv:

just migrate

Crie uma conta de superusuário com seu nome de usuário e senha para acessar o painel de administração:

just createsuperuser

Finalmente, inicie o servidor de desenvolvimento do Django usando o seu executor de tarefas:

just runserver

Abra localhost:8000 para ver a página de boas-vindas. Você deverá ver a tela de sucesso do Django confirmando que o servidor de desenvolvimento gerenciado pelo uv foi iniciado sem erros.

Em seguida, acesse localhost:8000/admin/ para fazer login no painel administrativo com suas credenciais de superusuário. Isso confirma que seu ambiente host se conectou ao PostgreSQL no Docker e que suas migrações foram executadas corretamente.