Skip to main content

​
Quick Start Tutorial

This tutorial will guide you through creating a complete Django SuperApp project with an admin portal and authentication system. By the end, you’ll have a running Django application with a modern admin interface.
This tutorial assumes you have already installed Django SuperApp. If not, please complete the installation first.

​
What You’ll Build

In this tutorial, you’ll create:
  • A Django SuperApp project with modular architecture
  • An admin portal with Django Unfold integration
  • An authentication app with user management
  • A fully Dockerized development environment

​
Create Your First Project

1

Bootstrap the Project

Create a new Django SuperApp project using the default template:
django_superapp bootstrap-project \
    --template-repo https://github.com/django-superapp/django-superapp-default-project \
    ./my_superapp
cd my_superapp
This command:
  • Downloads the project template from GitHub
  • Creates the base project structure
  • Sets up the modular app architecture
  • Configures settings.py to automatically discover apps
You can use any GitHub repository as a template by changing the --template-repo URL. This allows you to create custom project templates for your organization.
2

Add the Admin Portal App

Navigate to the apps directory and bootstrap the admin portal:
cd superapp/apps
django_superapp bootstrap-app \
    --template-repo https://github.com/django-superapp/django-superapp-admin-portal \
    ./admin_portal
cd ../../
The admin portal app includes:
  • Django Unfold admin interface
  • Custom admin site configuration
  • Pre-configured admin templates
  • Admin-specific URL patterns
The bootstrap-app command must be run from the superapp/apps directory. The CLI will check your current directory and raise an error if you’re not in the correct location.
3

Add the Authentication App

Add user authentication functionality:
cd superapp/apps
django_superapp bootstrap-app \
    --template-repo https://github.com/django-superapp/django-superapp-authentication \
    ./authentication
cd ../../
The authentication app provides:
  • User registration and login
  • Password reset functionality
  • User profile management
  • Integration with Django’s auth system
4

Set Up Environment Variables

Create your environment configuration file:
make setup-sample-env
This creates a .env.local file with default development settings. You can customize this file for your specific needs.
5

Start Docker Containers

Launch your application with Docker:
make start-docker
This command:
  • Builds the Docker images
  • Starts the web server and database
  • Sets up networking between containers
  • Exposes the application on port 8080
6

Load Environment Variables

Export the environment variables to your shell:
export $(cat .env.local | xargs)
This makes the configuration available to Django management commands.
7

Run Database Migrations

Apply all database migrations:
docker-compose exec web python3 manage.py migrate
This creates all necessary database tables for:
  • Django core tables
  • Admin portal models
  • Authentication models
  • Any other app-specific models
8

Create a Superuser

Create an admin account to access the admin portal:
docker-compose exec web python3 manage.py createsuperuser
Follow the prompts to enter:
  • Username
  • Email address
  • Password (twice for confirmation)
9

Access Your Application

Open your browser and navigate to:
http://localhost:8080/
You should see your Django SuperApp running! Log in with the superuser credentials you just created.Django SuperApp Admin Portal

​
Understanding the Project Structure

Your new Django SuperApp project has the following structure: 
my_superapp/
├── superapp/
│   ├── apps/
│   │   ├── admin_portal/      # Admin interface app
│   │   │   ├── settings.py    # App-specific settings
│   │   │   ├── urls.py        # App-specific URLs
│   │   │   └── ...
│   │   └── authentication/    # Authentication app
│   │       ├── settings.py    # App-specific settings
│   │       ├── urls.py        # App-specific URLs
│   │       └── ...
│   ├── settings.py            # Main settings (auto-discovers apps)
│   └── urls.py                # Main URLs (auto-includes app URLs)
├── docker-compose.yml
├── Dockerfile
├── manage.py
└── requirements.txt

​
How Automatic Discovery Works

Django SuperApp automatically discovers and integrates your apps:

​
Settings Integration

When you add a new app, Django SuperApp looks for a settings.py file with an extend_superapp_settings() function: 
# In your app's settings.py
def extend_superapp_settings(main_settings):
    # Add installed apps
    main_settings.INSTALLED_APPS.append('your_app')
    
    # Modify settings
    main_settings.CUSTOM_SETTING = 'value'

​
URL Integration

Similarly, for URLs, Django SuperApp looks for a urls.py file with an extend_superapp_urlpatterns() function: 
# In your app's urls.py
def extend_superapp_urlpatterns(main_urlpatterns):
    from django.urls import path
    from . import views
    
    main_urlpatterns.append(
        path('your-app/', views.index, name='your_app_index')
    )

​
Next Steps

Congratulations! You’ve created your first Django SuperApp project. Here are some ideas for what to do next:

Add More Apps

Bootstrap additional apps for your specific features using django_superapp bootstrap-app

Customize Templates

Modify your app templates and sync them back with push-template

Deploy to Production

Configure your production environment and deploy your application

Explore the Code

Dive into the generated code to understand how everything works together

​
Common Commands

Here are some useful commands you’ll use frequently: 
# Start the development server
make start-docker

# Stop the containers
docker-compose down

# Run migrations
docker-compose exec web python3 manage.py migrate

# Create a new app
cd superapp/apps && django_superapp bootstrap-app --template-repo <repo-url> ./app_name

# Update an app from its template
django_superapp pull-template ./superapp/apps/app_name

# Run Django management commands
docker-compose exec web python3 manage.py <command>

# Access Django shell
docker-compose exec web python3 manage.py shell

# Run tests
docker-compose exec web python3 manage.py test

​
Getting Help

If you encounter any issues: Happy building with Django SuperApp!

Build docs developers (and LLMs) love

Get started for freeTalk to us