Getting Started with Django SmallStack¶

Welcome to Django SmallStack v0.4.0! This is a Django 6.0+ starter project that provides a solid foundation for building admin-style web applications.

What's Included¶

Custom User Model - Flexible user authentication out of the box
User Profiles - Profile management with photo uploads
Admin Theme - Clean, modern UI with dark/light mode
Help System - Built-in documentation with markdown support
Background Tasks - Django 6's task framework pre-configured
Logging & Audit Trail - Sensible logging defaults and built-in activity tracking using Django's LogEntry
Website App - Scaffold for your project's pages (home, about, etc.)
Starter Template - Copy-paste template for creating new pages
Responsive Design - Works on desktop and mobile
Docker Ready - Deploy anywhere with Docker

Quick Start¶

Prerequisites¶

Python 3.12+
UV package manager (recommended)
Docker Desktop (for containerized deployment)

Local Development¶

SmallStack includes a Makefile with shortcuts for all common commands. See Make Commands for the full reference.

Clone and enter the project: bash cd django-smallstack
Run setup (installs all dependencies including dev tools, runs migrations, creates superuser): bash make setup
Set up environment variables (optional — defaults work out of the box): bash cp .env.example .env # Edit .env with your settings
Start the development server: bash make run
Open your browser:
Homepage: http://localhost:8005
Admin: http://localhost:8005/admin

That's it — two commands to go from clone to running app.

Verify Everything Works¶

make test         # Run the test suite (33 tests)
make lint         # Check code style

Project Structure Overview¶

SmallStack separates "customize freely" areas from "core" areas:

django-smallstack/
├── apps/
│   ├── website/           # CUSTOMIZE: Your pages (home, about, etc.)
│   ├── help/
│   │   └── content/
│   │       ├── index.md   # CUSTOMIZE: Your welcome page
│   │       └── smallstack/ # REFERENCE: SmallStack docs
│   ├── profile/           # EXTEND: User profiles
│   ├── tasks/             # EXTEND: Background tasks
│   ├── accounts/          # CORE: User authentication
│   └── smallstack/       # CORE: Theme system
├── templates/
│   ├── website/           # CUSTOMIZE: Your page templates (thin wrappers)
│   └── smallstack/
│       └── pages/         # UPSTREAM: SmallStack marketing content
├── config/                # CUSTOMIZE: Settings & deployment
├── static/
│   ├── smallstack/        # UPSTREAM: Core theme, brand, help assets
│   ├── brand/             # CUSTOMIZE: Your brand assets
│   ├── css/               # CUSTOMIZE: Your CSS overrides
│   └── js/                # CUSTOMIZE: Your JS
└── docs/                  # Additional documentation

Making It Your Own¶

SmallStack is designed to be forked and customized. Here's what to do first:

1. Customize Your Homepage¶

SmallStack's page templates use a thin wrapper + include pattern. The default templates/website/home.html includes SmallStack's marketing content via {% include %}. To customize, replace the include with your own markup:

{% extends "smallstack/base.html" %}
{% load theme_tags %}

{% block title %}Home{% endblock %}
{% block breadcrumbs %}{% endblock %}

{% block content %}
<div class="hero-section">
    <div class="hero-content">
        <h1 class="hero-title">My App</h1>
        <p class="hero-subtitle">Your tagline here.</p>
    </div>
</div>
{% endblock %}

Do the same for templates/website/about.html and templates/starter.html. Once replaced, upstream SmallStack updates to marketing content (in templates/smallstack/pages/) won't cause merge conflicts with your pages.

2. Update Your Branding¶

Replace "SmallStack" in these files:

File	What to Change
`templates/smallstack/base.html`	Title suffix, footer copyright
`templates/smallstack/includes/topbar.html`	Logo text
`templates/registration/*.html`	Page titles

Quick replace:

# Replace in all registration templates
find templates/registration -name "*.html" -exec sed -i '' 's/SmallStack/MyApp/g' {} \;

3. Set Up Your Documentation¶

Edit apps/help/content/index.md to create your project's welcome page. You can: - Keep SmallStack docs as reference in /help/smallstack/ - Add your own docs at /help/your-page/ - Remove SmallStack docs entirely

See the Customization Guide for detailed instructions.

Creating New Pages¶

In the Website App (Recommended)¶

For project-specific pages like landing pages, pricing, features:

Add a view in apps/website/views.py: python def pricing_view(request): return render(request, "website/pricing.html")
Add a URL in apps/website/urls.py: python urlpatterns = [ path("", views.home_view, name="home"), path("pricing/", views.pricing_view, name="pricing"), ]
Create the template templates/website/pricing.html

Using the Starter Template¶

The starter page at /starter/ demonstrates all available UI components. To create a new page based on it:

Create a new template (don't copy starter.html — it's a thin wrapper). Instead, create a fresh template: ```html {% extends "smallstack/base.html" %}

{% block title %}My Page{% endblock %}

{% block breadcrumbs %} {% breadcrumb "Home" "website:home" %} {% breadcrumb "My Page" %} {% render_breadcrumbs %}

{% block content %}

{% endblock %} ```

Create a view (see above)
Add to sidebar in templates/smallstack/includes/sidebar.html

Visit /starter/ to see all available components in action.

Deployment Setup¶

Before deploying, update the Kamal configuration:

config/deploy.yml¶

service: myapp              # Your app name

servers:
  web:
    - 123.45.67.89          # Your VPS IP

volumes:
  - /root/myapp_data/media:/app/media   # Update path
  - /root/myapp_data/db:/app/data

proxy:
  hosts:
    - myapp.com             # Your domain
    - www.myapp.com

.kamal/secrets¶

Copy from secrets.example and configure:

cp .kamal/secrets.example .kamal/secrets
# Edit with your values

See Kamal Deployment for full instructions.

Next Steps¶

Customization Guide - Make SmallStack your own
View the Starter Page - See all components in action
Customize the theme - Colors, dark mode, components
Deploy with Kamal - Zero-downtime VPS deployment
Explore the structure - Understand the codebase

Getting Help¶

If you run into issues:

Check the FAQ for common questions
Review the project structure
Open an issue on GitHub