Lithium: A Django-Powered Boilerplate

Lithium is a batteries-included Django starter project with everything you need to start coding, including user authentication, static files, default styling, debugging, DRY forms, custom error pages, and more.

This project was formerly known as DjangoX but was renamed to Lithium in November 2024.

https://github.com/user-attachments/assets/8698e9dd-1794-4f96-9c3f-85add17e330b

🚀 Features

Django 6.0 & Python 3.13
Installation via uv, Pip or Docker
User authentication--log in, sign up, password reset--via django-allauth
Static files configured with Whitenoise
Styling with Bootstrap v5
Debugging with django-debug-toolbar
DRY forms with django-crispy-forms
Custom 404, 500, and 403 error pages

📖 Installation

Lithium can be installed via Pip or Docker. To start, clone the repo to your local computer and change into the proper directory.

$ git clone https://github.com/wsvincent/lithium.git
$ cd lithium

uv

You can use uv to create a dedicated virtual environment.

$ uv sync

Then run migrate to configure the initial database. The command createsuperuser will create a new superuser account for accessing the admin. Execute the runserver command to start up the local server.

$ uv run manage.py migrate
$ uv run manage.py createsuperuser
$ uv run manage.py runserver
Load the site at http://127.0.0.1:8000 or http://127.0.0.1:8000/admin for the admin

Pip

To use Pip, create a new virtual environment and then install all packages hosted in requirements.txt. Run migrate to configure the initial database. and createsuperuser to create a new superuser account for accessing the admin. Execute the runserver command to start up the local server.

(.venv) $ pip install -r requirements.txt
(.venv) $ python manage.py migrate
(.venv) $ python manage.py createsuperuser
(.venv) $ python manage.py runserver
Load the site at http://127.0.0.1:8000 or http://127.0.0.1:8000/admin for the admin

Docker

To use Docker with PostgreSQL as the database update the DATABASES section of django_project/settings.py to reflect the following:

# django_project/settings.py
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": "postgres",
        "USER": "postgres",
        "PASSWORD": "postgres",
        "HOST": "db",  # set in docker-compose.yml
        "PORT": 5432,  # default postgres port
    }
}

The INTERNALIPS configuration in djangoproject/settings.py must be also be updated:

# config/settings.py
django-debug-toolbar
import socket
hostname, , ips = socket.gethostbynameex(socket.gethostname())
INTERNAL_IPS = [ip[:-1] + "1" for ip in ips]

And then proceed to build the Docker image, run the container, and execute the standard commands within Docker.

$ docker compose up -d --build
$ docker compose exec web python manage.py migrate
$ docker compose exec web python manage.py createsuperuser
Load the site at http://127.0.0.1:8000 or http://127.0.0.1:8000/admin for the admin

Next Steps

Add environment variables. There are multiple packages but I personally prefer environs.
Add gunicorn as the production web server.
Update the EMAILBACKEND and connect with a mail provider.
Make the admin more secure.
django-allauth supports social authentication if you need that.