Django Boilerplate

My personal and very opinionated Django boilerplate for quickly starting projects. It features:

• Django Unfold Admin Panel
• Django Simple History
• Django Browser Reload
• Django Tailwind (with FlyonUI)
• Django Cotton
• Django HTMX
• Celery with Redis for background tasks
• PostgreSQL database
• Full Docker development environment with devcontainer support

Prerequisites

• Docker
• VSCode or Cursor with Dev Containers extension (recommended)

Quick Start

1. Clone the repository

git clone [email protected]:davidbogas/django-boilerplate.git
cd django-boilerplate

2. Setup environment variables

Copy the example environment file and customize it:

cp .env.example .env

Edit the .env file and adjust the variables as needed for your environment.

3. Development with VSCode/Cursor (Recommended)

1. Open the project in VSCode or Cursor
2. When prompted, click "Reopen in Container" or use Ctrl+Shift+P → "Dev Containers: Reopen in Container"
3. The editor will automatically build and start the development environment

4. Development with Make commands

Use the included Makefile for easy development:

# Start all services
make up

# Apply migrations
make migrate

# Create a superuser
make createsuperuser

# Run tests
make test

# Open Django shell
make shell

# View all available commands
make help

5. Access the application

• Django app: http://localhost:8000
• Admin panel: http://localhost:8000/admin

Development Commands

The project includes a Makefile with useful commands:

Command	Description
make up	Start all services
make down	Stop all services
make build	Build containers
make restart	Restart services
make shell	Open Django shell
make bash	Open bash in web container
make makemigrations	Create new migrations
make migrate	Apply migrations
make createsuperuser	Create Django superuser
make test	Run all tests
make logs	Show logs for all services
make clean	Remove containers and volumes
make rebuild	Clean build and restart

Production Deployment

1. Build production containers

docker compose --profile prod build

2. Start production services

docker compose --profile prod up -d

Project Structure

├── app/                   # Django application
│   ├── config/            # Django settings and configuration
│   ├── home/              # Home app
│   ├── users/             # Custom user model
│   ├── theme/             # Tailwind CSS theme
│   └── static/            # Static files
├── compose/               # Docker configuration
├── requirements/          # Python dependencies
├── .devcontainer/         # VSCode devcontainer configuration
├── docker-compose.yml     # Docker compose configuration
├── Makefile               # Development commands
├── README.md              # This file
└── .env.example           # Environment variables example