Installation Guide¶

This guide will walk you through installing and configuring django-admin-deux in your Django project.

Requirements¶

Python and Django Versions¶

django-admin-deux supports the following versions:

Python	Django 5.2	Django 6.0
3.11	✅	✅
3.12	✅	✅
3.13	✅	✅
3.14	✅	✅

Dependencies¶

djp: Django plugin system (installed automatically)
pluggy: Hook system (dependency of djp)

Installation Steps¶

1. Install via pip¶

Basic installation:

pip install django-admin-deux

With all plugins (recommended):

pip install django-admin-deux[full]
# Installs djadmin-formset and djadmin-filters

With specific plugins:

pip install django-admin-deux[formset]   # Just djadmin-formset for Layout API
pip install django-admin-deux[filters]   # Just djadmin-filters for filtering/search

Using uv:

uv pip install django-admin-deux[full]

2. Add to INSTALLED_APPS¶

Add djadmin to your INSTALLED_APPS in settings.py:

Recommended - Automatic plugin discovery:

# settings.py
from djadmin import djadmin_apps

INSTALLED_APPS = [
    # Django apps
    'django.contrib.admin',  # Can coexist with djadmin
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # django-admin-deux (automatically includes all plugins with correct ordering)
    *djadmin_apps(),

    # Your apps
    'myapp',
]

What djadmin_apps() does: - Automatically discovers installed plugins (djadmin-formset, djadmin-filters, contrib_auth, etc.) - Ensures correct ordering (plugins before djadmin for template overrides) - Includes core plugin and theme plugin automatically - No manual maintenance needed when adding/removing plugins

Built-in Plugins Included: - djadmin.plugins.core - Always enabled, provides CRUD features - djadmin.plugins.theme - Default Tailwind CSS theme - djadmin.plugins.contrib_auth - Pre-built User and Group admin (optional)

Manual configuration (advanced): If you need fine-grained control over ordering:

INSTALLED_APPS = [
    # Django apps...
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    # Plugin dependencies (if using plugins)
    'django_filters',  # Required by djadmin-filters
    'formset',         # Required by djadmin-formset

    # Plugins (MUST be before djadmin for template overrides)
    'djadmin_formset',  # If installed
    'djadmin_filters',  # If installed
    'djadmin.plugins.contrib_auth',  # Optional: User/Group admin
    'djadmin.plugins.theme',  # Default theme

    # django-admin-deux core
    'djadmin',

    # Your apps
    'myapp',
]

Note: The theme plugin is optional. If you don't include it, you'll need to provide your own theme plugin or templates.

Optional: Enable contrib_auth Plugin¶

To add pre-built admin interfaces for Django's User and Group models, add the plugin to INSTALLED_APPS:

# settings.py
from djadmin import djadmin_apps

INSTALLED_APPS = [
    # Django apps...
    'django.contrib.auth',

    # Add contrib_auth plugin
    'djadmin.plugins.contrib_auth',

    # django-admin-deux (or use djadmin_apps())
    *djadmin_apps(),

    # Your apps...
]

The plugin provides: - UserAdmin - Complete user management with password change action - GroupAdmin - Group and permissions management - Works with custom user models via AUTH_USER_MODEL - Automatic registration when plugin is in INSTALLED_APPS

See the contrib_auth Plugin Guide for full documentation.

3. Configure URLs¶

Add djadmin URLs to your project's urls.py:

# urls.py
from django.contrib import admin
from django.urls import path, include
from djadmin import site

urlpatterns = [
    path('admin/', admin.site.urls),  # Django admin (optional, can coexist)
    path('djadmin/', include(site.urls)),
    path('accounts/', include('django.contrib.auth.urls')),  # Required for login/logout
]

Important Notes: - site.urls automatically provides namespace support. You can use reverse lookups like reverse('djadmin:index') or reverse('djadmin:app_model_list'). The namespace is automatically set to the site's name (default: 'djadmin'). - Authentication URLs are required: django-admin-deux uses Django's built-in authentication system. The accounts/ URLs provide login, logout, and password reset views. - LOGIN_URL setting: Ensure your settings.py has LOGIN_URL = '/accounts/login/' (or adjust the path to match your URL configuration).

4. Collect Static Files¶

Run Django's collectstatic command to collect djadmin's static files:

python manage.py collectstatic

This collects: - CSS files (theme.css) - JavaScript files (admin.js for dark mode) - SVG icons

5. Create Your First ModelAdmin¶

Create a djadmin.py file in one of your Django apps:

# myapp/djadmin.py
from djadmin import ModelAdmin, register
from .models import Book

@register(Book)
class BookAdmin(ModelAdmin):
    list_display = ['title', 'author', 'published_date']

6. Start the Development Server¶

python manage.py runserver

Navigate to http://127.0.0.1:8000/djadmin/ to see your admin interface!

Configuration Options¶

Custom AdminSite¶

You can create custom AdminSite instances:

# myapp/admin.py
from djadmin import AdminSite, ModelAdmin
from .models import Book

# Create custom site
my_site = AdminSite(name='myadmin')

class BookAdmin(ModelAdmin):
    list_display = ['title', 'author']

my_site.register(Book, BookAdmin)

Then include it in your URLs:

# urls.py
from myapp.admin import my_site

urlpatterns = [
    path('myadmin/', include(my_site.urls)),
]

Note: The custom site will use its own namespace based on the name parameter (in this example: 'myadmin').

Theme Configuration¶

The default theme plugin (djadmin.plugins.theme) is automatically included by djadmin_apps().

To use a custom theme:

Simply install a custom theme package. The custom theme will automatically take precedence over the default theme due to Django's template loading order.

# Example: Install a hypothetical custom theme
pip install djadmin-theme-material

The theme plugin will be automatically discovered and included via djadmin_apps().

Note: No custom themes are available yet. The default theme provides a clean, modern interface with Tailwind CSS and dark mode support.

See the Custom Theme Guide for creating your own themes.

Coexistence with Django Admin¶

django-admin-deux can coexist with Django's built-in admin:

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',  # Django admin
    'djadmin',               # django-admin-deux
    # ...
]

# urls.py
urlpatterns = [
    path('admin/', admin.site.urls),      # Django admin at /admin/
    path('djadmin/', include(site.urls)), # djadmin at /djadmin/
]

You can register models in both admin interfaces:

# Django admin
from django.contrib import admin
admin.site.register(Book)

# django-admin-deux
from djadmin import register, ModelAdmin
@register(Book)
class BookAdmin(ModelAdmin):
    pass

Verification¶

To verify your installation:

Check URLs: Navigate to /djadmin/ - you should see the project dashboard
Check Static Files: The page should be styled (Tailwind CSS loaded)
Check Dark Mode: Toggle dark mode button in navigation should work
Check Models: Your registered models should appear in the dashboard

Troubleshooting¶

Static Files Not Loading¶

Problem: Page appears unstyled, CSS not loading.

Solution: Run python manage.py collectstatic and ensure your static files configuration is correct:

# settings.py
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'

ImportError: No module named 'djadmin'¶

Problem: Python can't find the djadmin module.

Solution: Ensure django-admin-deux is installed in your active environment:

pip show django-admin-deux

If not installed:

pip install django-admin-deux

404 on /djadmin/¶

Problem: Page not found when accessing /djadmin/.

Solution: Ensure you've added djadmin URLs to your urls.py:

from djadmin import site
urlpatterns = [
    path('djadmin/', include(site.urls)),
]

No Models Showing in Dashboard¶

Problem: Dashboard is empty, no models appear.

Solution: 1. Ensure you've created a djadmin.py file with @register() decorators 2. Ensure your app is in INSTALLED_APPS 3. Restart the development server

ImproperlyConfigured: Feature 'X' not provided¶

Problem: Error about missing feature (e.g., 'search', 'filter').

Solution: You're using a ModelAdmin configuration that requires a plugin:

# This requires a search plugin:
class BookAdmin(ModelAdmin):
    search_fields = ['title']  # ERROR: 'search' feature not provided

Either: - Remove the feature indicator (search_fields), or - Install a plugin that provides the feature

Next Steps¶

Now that you have django-admin-deux installed:

Getting Started Tutorial - Create your first ModelAdmin
Basic Usage Guide - Learn ModelAdmin configuration
Action System Guide - Understand the action system

Upgrading¶

From Pre-1.0 Versions¶

django-admin-deux is currently in active development. Breaking changes may occur before 1.0 release.

When upgrading: 1. Check the CHANGELOG for breaking changes 2. Update your djadmin.py files if needed 3. Run tests to ensure compatibility

Development Installation¶

If you want to contribute or run the latest development version:

# Clone the repository
git clone https://gitlab.levitnet.be/levit/django-admin-deux.git
cd django-admin-deux

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all plugins
pip install -e ".[dev]"

# Install plugins in development mode
cd djadmin-formset
pip install -e .
cd ../djadmin-filters
pip install -e .
cd ..

# Run tests
pytest

What this installs: - Main package (djadmin) in editable mode - Both plugins (djadmin-formset, djadmin-filters) in editable mode - All development dependencies (pytest, ruff, djlint, etc.)

See CLAUDE.md for detailed development documentation.