README.md

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.

djangox_screencast.mov

👋 Free Newsletter

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

🚀 Features

• Django 5.1 & Python 3.12
• Installation via 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
  • 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

Pip

You can use pip to create a fresh virtual environment on either Windows or macOS.

# On Windows
$ python -m venv .venv
$ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
$ .venv\Scripts\Activate.ps1
(.venv) $

# On macOS
$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $

Then install all packages hosted in requirements.txt and 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.

(.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