djangox

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

👋 Free Newsletter

Sign up for updates to the free and upcoming premium SaaS version!

🚀 Features

• Django 5.1 & 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

Table of Contents

• Installation
  • uv
  • Pip
  • Docker
• Next Steps
• Contributing
• Support
• License

📖 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 commandt o 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 commandt o 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 INTERNAL_IPS configuration in django_project/settings.py must be also be updated:

# config/settings.py
# django-debug-toolbar
import socket
hostname, _, ips = socket.gethostbyname_ex(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 EMAIL_BACKEND and connect with a mail provider.
• Make the admin more secure.
• django-allauth supports social authentication if you need that.

I cover all of these steps in tutorials and premium courses over at LearnDjango.com.

🤝 Contributing

Contributions, issues and feature requests are welcome! See CONTRIBUTING.md.

⭐️ Support

Give a ⭐️ if this project helped you!

License

The MIT License