Getting Started with Django SmallStack¶

Welcome to Django SmallStack v0.2.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
• 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¶

1. Clone and enter the project: bash cd django-smallstack

2. Install dependencies: bash uv sync

3. Set up environment variables: bash cp .env.example .env # Edit .env with your settings

4. Run migrations: bash uv run python manage.py migrate

5. Create a superuser: bash uv run python manage.py create_dev_superuser

6. Start the development server: bash uv run python manage.py runserver

7. Open your browser:

8. Homepage: http://localhost:8000
9. Admin: http://localhost:8000/admin

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
│   └── admin_theme/       # CORE: Theme system
├── templates/
│   └── website/           # CUSTOMIZE: Your page templates
├── config/                # CUSTOMIZE: Settings & deployment
├── static/                # CSS, JS, images
└── 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¶

Edit templates/website/home.html with your own content:

{% extends "admin_theme/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 %}

2. Update Your Branding¶

Replace "SmallStack" in these files:

File	What to Change
templates/admin_theme/base.html	Title suffix, footer copyright
templates/admin_theme/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:

1. Add a view in apps/website/views.py: python def pricing_view(request): return render(request, "website/pricing.html")

2. Add a URL in apps/website/urls.py: python urlpatterns = [ path("", views.home_view, name="home"), path("pricing/", views.pricing_view, name="pricing"), ]

3. Create the template templates/website/pricing.html

Using the Starter Template¶

For admin-style pages, copy the starter template:

1. Copy the template: bash cp templates/starter.html templates/my_page.html

2. Create a view (see above)

3. Add to sidebar in templates/admin_theme/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:

1. Check the FAQ for common questions
2. Review the project structure
3. Open an issue on GitHub