Setup Drf Project

Setup DRF Project

Workflow

Use this skill to create a new DRF backend in the current directory or to carefully adapt an incomplete project. Prefer the bundled script for new or mostly empty directories:

python /home/mf/.codex/skills/setup-drf-project/scripts/setup_drf_project.py .

When the backend lives in a backend/ directory, run the script from that directory or pass that directory as the target. The generated project is isolated and owns its local development infrastructure:

backend/
├── database/
│   └── Dockerfile
├── docker-compose.yml
├── Dockerfile
└── ...

Use --force only after inspecting the target directory and confirming overwrites are intended:

python /home/mf/.codex/skills/setup-drf-project/scripts/setup_drf_project.py . --force

The script creates:

• core/ Django project files
• apps/accounts/ with a custom User, admin, serializer with password hashing, authenticated user CRUD, MeView, URLs, and migrations package
• backend files: .env, .env.example, .gitignore, requirements.txt, and Dockerfile
• architecture decision records under docs/adr/
• local infrastructure files: database/Dockerfile and docker-compose.yml inside the backend directory
• split settings for development and production, django-environ, PostgreSQL, DRF, Simple JWT, CORS, default authenticated permissions, page-number pagination, AUTH_USER_MODEL, Portuguese/Brazilian locale, and America/Manaus
• production-ready defaults: Gunicorn container command, .dockerignore, console logging, production security settings, and GET /api/health/

If docker-compose.yml already exists in the backend directory, inspect it and add only the PostgreSQL db service pointing to ./database/Dockerfile, plus the postgres_data volume if missing. Preserve existing services and do not rewrite the whole compose file unless the user explicitly asks.

Manual Fallback

If the script cannot be used, perform the same steps incrementally:

1. Install dependencies:

pip install django djangorestframework djangorestframework-simplejwt "psycopg[binary]" django-environ django-cors-headers

2. Start the project before creating app files:

django-admin startproject core .
mkdir -p apps
touch apps/__init__.py
mkdir -p apps/accounts
python manage.py startapp accounts apps/accounts

3. Configure apps/accounts/apps.py with name = "apps.accounts".
4. Create apps/accounts/models.py with User(AbstractUser) and unique email.
5. Register CustomUserAdmin in apps/accounts/admin.py.
6. Replace the generated core/settings.py with a core/settings/ package before migrations:
   • core/settings/base.py
   • core/settings/development.py
   • core/settings/production.py
   • core/settings/__init__.py
7. Configure settings:
   • import environ and timedelta
   • read BASE_DIR / ".env"
   • use SECRET_KEY = env("SECRET_KEY"), DEBUG = env("DEBUG"), ALLOWED_HOSTS = env.list(...)
   • add rest_framework, rest_framework_simplejwt, corsheaders, and apps.accounts.apps.AccountsConfig
   • put corsheaders.middleware.CorsMiddleware before common/session middleware
   • set AUTH_USER_MODEL = "accounts.User"
   • set DATABASES = {"default": env.db("DATABASE_URL")}
   • configure CORS_ALLOWED_ORIGINS, REST_FRAMEWORK, and SIMPLE_JWT
   • set DRF pagination with DEFAULT_PAGINATION_CLASS = "core.pagination.DefaultPagination", PAGE_SIZE = 10, and MAX_PAGE_SIZE = 100
   • configure production security settings in production.py
   • configure console logging
8. Update manage.py and asgi.py to default to core.settings.development; update wsgi.py to default to core.settings.production.
9. Update core/urls.py with admin, GET /api/health/, Simple JWT token endpoints, and path("api/accounts/", include("apps.accounts.urls")).
10. Add core/pagination.py with a DefaultPagination class using page_size_query_param = "page_size" and max_page_size from settings.
11. Add core/views.py with an unauthenticated HealthCheckView.
12. Add serializers.py, views.py, and urls.py for GET /api/accounts/me/ and authenticated user CRUD under /api/accounts/users/; restrict the user CRUD viewset to admin users.
13. Add backend files: .env, .env.example, requirements.txt, .gitignore, .dockerignore, and Dockerfile.
14. Add ADRs under docs/adr/ documenting the backend architecture, isolated Compose decision, and production-readiness settings.
15. Add database/Dockerfile inside the backend directory.
16. Add or update the backend docker-compose.yml; if it already exists, add only the db service that builds from ./database/Dockerfile and the postgres_data volume if missing.

Always inspect existing files before replacing them. Preserve unrelated existing code and report any conflict instead of deleting it.

Validation

Run validation only after AUTH_USER_MODEL and INSTALLED_APPS are correct:

python manage.py makemigrations
python manage.py migrate
python manage.py check

For Docker:

docker compose up --build

Optionally create a superuser:

python manage.py createsuperuser

Endpoint Checks

After the server is running and a user exists, test JWT:

curl -X POST http://localhost:8000/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}'

Use the token:

curl http://localhost:8000/api/accounts/me/ \
  -H "Authorization: Bearer ACCESS_TOKEN_AQUI"

List users:

curl http://localhost:8000/api/accounts/users/ \
  -H "Authorization: Bearer ACCESS_TOKEN_AQUI"

Create a user:

curl -X POST http://localhost:8000/api/accounts/users/ \
  -H "Authorization: Bearer ACCESS_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"username": "user1", "email": "user1@example.com", "password": "change-me"}'

Update and delete use /api/accounts/users/<id>/ with PUT, PATCH, or DELETE.

Health check:

curl http://localhost:8000/api/health/

Reporting

At the end, summarize files created or changed, validation results, commands to run the project, and the two curl examples above. If migrations or Docker are not run, state exactly why.

Also mention the generated ADR path and summarize the decisions it records.