Guida per avviare un progetto in Django

4 minuti

Vista grafico

Guida per avviare un progetto in Django

Contesto

Django è un framework web Python di alto livello che segue il principio “batteries included”: offre ORM, pannello admin, sistema di autenticazione, gestione delle URL e molto altro out of the box. È la scelta ideale per costruire applicazioni web robuste e scalabili in tempi rapidi.

Questa guida copre l’intero ciclo di avvio di un progetto Django professionale: dall’ambiente virtuale alla prima app funzionante, passando per configurazione, database e struttura dei file.

Analisi

1. Prerequisiti

  • Python 3.10+ installato (python3 --version)
  • pip o uv disponibile
  • Conoscenza base di Python e del pattern MVC/MVT

2. Creare l’ambiente virtuale

Isolare le dipendenze del progetto è fondamentale.

# Con venv (stdlib)
python3 -m venv .venv
source .venv/bin/activate        # Linux/macOS
# oppure su Windows:
# .venv\Scripts\activate
 
# Verifica
which python   # deve puntare a .venv/

Alternativa moderna: usa uv venv + uv pip install per velocità molto superiore.

3. Installare Django

pip install django
# oppure con versione specifica:
pip install "django>=5.0,<6.0"
 
# Verifica
python -m django --version

Congela subito le dipendenze:

pip freeze > requirements.txt

4. Creare il progetto

django-admin startproject myproject .

Il punto finale . evita una cartella doppia. La struttura risultante:

.
├── manage.py
├── requirements.txt
├── .venv/
└── myproject/
    ├── __init__.py
    ├── settings.py
    ├── urls.py
    ├── asgi.py
    └── wsgi.py

5. Struttura consigliata per progetti reali

Per progetti non banali, organizza le app in una cartella apps/:

.
├── manage.py
├── requirements.txt
├── myproject/
│   ├── settings/
│   │   ├── base.py
│   │   ├── development.py
│   │   └── production.py
│   ├── urls.py
│   └── wsgi.py
└── apps/
    └── core/

Split dei settings per ambiente (base / development / production) è una best practice essenziale.

6. Configurare il database

Django usa SQLite di default, ma per progetti seri preferisci PostgreSQL.

# settings/base.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "myproject_db",
        "USER": "myuser",
        "PASSWORD": "mypassword",
        "HOST": "localhost",
        "PORT": "5432",
    }
}

Installa il driver:

pip install psycopg2-binary

Esegui le migrazioni iniziali:

python manage.py migrate

7. Creare la prima app

In Django un progetto è composto da più app (moduli funzionali):

python manage.py startapp core apps/core

Registra l’app in settings.py:

INSTALLED_APPS = [
    ...
    "apps.core",
]

Struttura di una app:

apps/core/
├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── views.py
├── urls.py
└── migrations/

8. Primo modello, view e URL

models.py

from django.db import models
 
class Article(models.Model):
    title = models.CharField(max_length=200)
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
 
    def __str__(self):
        return self.title

views.py

from django.http import JsonResponse
from .models import Article
 
def article_list(request):
    articles = list(Article.objects.values("id", "title", "created_at"))
    return JsonResponse(articles, safe=False)

urls.py (app)

from django.urls import path
from . import views
 
urlpatterns = [
    path("articles/", views.article_list, name="article-list"),
]

urls.py (progetto)

from django.urls import path, include
 
urlpatterns = [
    path("api/", include("apps.core.urls")),
]

9. Superuser e pannello admin

python manage.py createsuperuser

Registra i modelli nell’admin:

# admin.py
from django.contrib import admin
from .models import Article
 
admin.site.register(Article)

Accedi a http://127.0.0.1:8000/admin/ per gestire i dati visualmente.

10. Variabili d’ambiente con python-dotenv

Non mettere mai segreti nel codice. Usa un file .env:

pip install python-dotenv
# settings/base.py
from pathlib import Path
from dotenv import load_dotenv
import os
 
load_dotenv()
 
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DEBUG", "False") == "True"

Crea .env (e aggiungilo a .gitignore!):

DJANGO_SECRET_KEY=la-tua-chiave-segreta
DEBUG=True

11. Avviare il server di sviluppo

python manage.py runserver

Apri http://127.0.0.1:8000/ nel browser.

12. Checklist prima del primo commit

  • .env aggiunto a .gitignore
  • requirements.txt aggiornato
  • Migrazioni eseguite
  • SECRET_KEY non hardcoded
  • DEBUG=False in production settings
  • ALLOWED_HOSTS configurato per production

Considerazioni finali

Django brilla per la sua coerenza e la ricchezza dell’ecosistema. Seguire fin dall’inizio una struttura pulita (split settings, app modulari, variabili d’ambiente) risparmia enormi refactoring in seguito.

Per il passo successivo considera:

  • Django REST Framework se costruisci una API
  • Celery + Redis per task asincroni
  • django-debug-toolbar per il debug in development
  • gunicorn + nginx per il deploy in produzione

La documentazione ufficiale di Django è tra le migliori nel mondo open source: consultala sempre come riferimento primario.

Riferimenti

Python Backend Development Web Framework

Vista grafico