# Skill Prompt: Install SmallStack You are helping a user set up a new Django SmallStack project. SmallStack is a Django starter that provides authentication, a staff dashboard, model Explorer (auto-generated CRUD), background tasks, theming, navigation, and optional REST API — out of the box. ## Step 1: Gather Requirements Before doing anything, ask the user these questions: ### Project Identity - **Project name** — used for directory name, branding, and settings (e.g., "Acme Portal") - **Domain** (if known) — for production settings later (e.g., "acme.example.com") ### Theme Strategy Ask the user to choose one of these options: > **How would you like your UI to look?** > > **A) Custom theme for landing pages only** > Your public-facing pages (home, about, pricing) use your own design (Bootstrap, Tailwind, plain CSS, etc.). Staff tools like Explorer, Activity, and Backups keep SmallStack's built-in theme at `/smallstack/`. Best when: your marketing site has a specific brand identity but internal tools don't need custom styling. > > **B) Custom theme for landing pages AND user pages** > Same as A, but authenticated user pages (dashboard, settings, app workflows) also use your custom theme. SmallStack staff tools still keep their own theme. Best when: end users interact with your app and need a polished, branded experience. > > **C) SmallStack theme for everything** > Use SmallStack's built-in theme (dark/light mode, sidebar, topbar, breadcrumbs) for all pages. No custom base template needed. Best when: building an internal tool, admin panel, or prototype where speed matters more than custom branding. Record their choice as `THEME_CHOICE` (A, B, or C) for later steps. > > **d) What port do you want to run on?** record their choice as `PORT` for later steps. ## Step 2: Clone and Setup Run these commands: ```bash git clone https://github.com/emichaud/django-smallstack.git <project-directory> cd <project-directory> rm -rf .git git init ``` Then run: ```bash make setup ``` This installs dependencies (via uv), runs migrations, and creates a dev superuser (`admin`/`admin`). Verify it works: ```bash make run ``` USE user selected port or 8000 Visit `http://localhost:8000/` — the home page should load. Visit `http://localhost:8000/smallstack/` and log in with `admin`/`admin` — the staff dashboard should appear. ## Step 3: Read the Setup Guide Read the full setup guide for detailed instructions on each phase: ``` docs/skills/from-zero-to-running.md ``` Follow **Phase 2 (Branding)** to update `BRAND_NAME`, `BRAND_TAGLINE`, logos, and favicon in `config/settings/base.py` and `static/brand/`. Ask the user for their brand name and any assets they have. ## Step 4: Apply Theme Strategy Based on the user's `THEME_CHOICE`: ### If A (Custom landing pages, SmallStack staff tools): Read `docs/skills/adding-your-own-theme.md` for the full walkthrough. Key steps: 1. Create `templates/<themename>/base.html` with the dark mode contract (see the from-zero guide Phase 3, Scenario A) 2. Create landing pages in `templates/website/` extending your custom base 3. Add views in `apps/website/views.py` and URLs in `apps/website/urls.py` 4. Staff pages (`/smallstack/*`) continue using SmallStack's theme — no changes needed Settings to consider: ```python SMALLSTACK_LOGIN_ENABLED = False # Hide login from SmallStack topbar if your theme has its own LOGIN_REDIRECT_URL = "/" LOGOUT_REDIRECT_URL = "/" ``` ### If B (Custom landing pages AND user pages): Same as A, plus: 1. Create authenticated page templates extending your custom base 2. Set `LOGIN_REDIRECT_URL` to your app's post-login page (e.g., `/dashboard/`) 3. Set `SMALLSTACK_SIGNUP_ENABLED = True` if you want public registration 4. Read `docs/skills/authentication.md` for auth view customization ### If C (SmallStack theme for everything): No custom base template needed. All pages extend `smallstack/base.html`: ```html {% extends "smallstack/base.html" %} {% load theme_tags %} {% block title %}My Page{% endblock %} {% block breadcrumbs %} {% breadcrumb "Home" "website:home" %} {% breadcrumb "My Page" %} {% render_breadcrumbs %} {% endblock %} {% block content %} <div class="card"> <div class="card-header"><h1>My Page</h1></div> <div class="card-body">Content here</div> </div> {% endblock %} ``` Read `docs/skills/templates.md` for available blocks and components. Read `docs/skills/theming-system.md` for CSS variables and color palettes. ## Step 5: Build the App Read these skill docs as needed for what the user wants to build: | Task | Skill Doc | |------|-----------| | Create a new Django app | `docs/skills/django-apps.md` | | Auto-generated CRUD (Explorer) | `docs/skills/explorer.md` | | Custom CRUD views | `docs/skills/crud-views.md` | | REST API | `docs/skills/api.md` | | Sidebar/topbar navigation | `docs/skills/navigation.md` | | Background tasks | `docs/skills/background-tasks.md` | | Help documentation | `docs/skills/help-documentation.md` | | Filtering and export | `docs/skills/filtering-export.md` | | HTMX patterns | `docs/skills/htmx-patterns.md` | | Theming and dark mode | `docs/skills/theming-system.md` | | User management | `docs/skills/user-management.md` | | Timezones | `docs/skills/timezones.md` | ### Quick Path: Register Models in Explorer The fastest way to get a working app is: 1. Create models in your app 2. Create `apps/<appname>/explorer.py` and register models with `explorer.register()` 3. Explorer autodiscovers on startup — models appear at `/smallstack/explorer/` ```python # apps/myapp/explorer.py from django.contrib import admin from apps.explorer.registry import explorer from .models import MyModel class MyModelAdmin(admin.ModelAdmin): list_display = ["field1", "field2", "field3"] explorer_enabled = True explorer.register(MyModel, MyModelAdmin, group="My App") ``` ### Named Explorer Instances (Workflow UIs) For user-facing workflows with their own URL space, forms, and templates: ```python # apps/myapp/sites.py from apps.explorer.registry import ExplorerSite, explorer workflow = ExplorerSite( name="workflow", parent=explorer, groups=["My App"], display_name="My Workflow", ) workflow.set_form(MyModel, MyWorkflowForm) # config/urls.py path("smallstack/workflow/", include(workflow.urls, namespace="workflow")) ``` Read `docs/skills/explorer.md` for the full Explorer API. For the vision and design rationale, see `ai_cowork/explorer-vision.md`. ## Step 6: Environment and Deployment When the user is ready to deploy, follow: - `docs/skills/docker-deployment.md` — Docker setup and local testing - `docs/skills/kamal-deployment.md` — Production deployment with Kamal - Phase 7-8 of `docs/skills/from-zero-to-running.md` — Step-by-step deployment checklist Key deployment files: - `.env` — local development settings - `.kamal/secrets` — production secrets (never committed) - `config/deploy.yml` — Kamal deployment config - `docker-compose.yml` — local Docker testing ## Important Conventions - All apps live in `apps/` and must use `name = "apps.<appname>"` in their `AppConfig` — this is the most common setup mistake - User model is always `settings.AUTH_USER_MODEL`, never a direct import - Protected views use `LoginRequiredMixin` or `StaffRequiredMixin` - URL namespaces: set `app_name` in `urls.py`, reference as `appname:viewname` - Navigation: register in `AppConfig.ready()` using `from apps.smallstack.navigation import nav` - Tests go in `apps/<appname>/tests/` - Run `make test` to verify, `make lint-fix` to format ## What NOT to Do - Don't modify `apps/smallstack/` or `apps/explorer/` for project-specific logic — those are upstream. Put project code in `apps/website/` or new apps. - Don't skip the `apps.` prefix in app names — Django will fail at startup. - Don't hardcode URL paths — use `reverse()` or `{% url %}` with named URLs. - Don't create `requirements.txt` — SmallStack uses `uv` and `pyproject.toml`.Copy