Local Development
Run these commands inside your downloaded, unzipped project, in the directory
containing manage.py, Makefile, and docker-compose-local.yml. You are
starting your own Django app, not a local copy of the hosted Djass generator.
If you have not downloaded a project yet, follow the
project generation workflow.
1) Prepare your local environment
Install Docker with Docker Compose and GNU Make for the container-based path
below. Docker runs Python, Node, PostgreSQL, and Redis for this path; you do not
need to install their runtimes on your host just to run make serve.
If you run Python or frontend commands directly on your machine, use uv and
the versions in your generated .python-version and .nvmrc. The bundled
starter checked on October 11, 2026 pins Python 3.14.5 and Node 24.15.0.
For an older download, follow that repository's pins and TECHNICAL.md rather
than mixing instructions from different versions.
Copy the development settings:
cp .env.example .env
Keep .env private. The example's credentials are local-development values,
not production secrets. For connection overrides and host-versus-container
addresses, follow the generated-app configuration checklist.
For Docker Compose, leave POSTGRES_HOST=db and
REDIS_HOST=redis; those names identify services inside the Compose network.
If another app already uses the default ports, change the relevant LOCAL_*
values in .env. Keep SITE_URL aligned with LOCAL_WEB_PORT: for example,
port 8001 needs SITE_URL=http://localhost:8001. Published host ports do not
change the database or Redis ports used between containers.
2) Start the app and supporting services
From the generated project root, run:
make serve
This builds and starts the Compose stack in the background, then follows the backend logs. The backend applies migrations before starting the web server. Use a second terminal for the commands below. Pressing Ctrl+C in the log terminal stops following logs; it does not stop the running containers.
The core services are PostgreSQL, Redis, the Django backend, a Django Q2 worker, the frontend asset watcher, and Mailhog. The frontend container compiles assets into the shared project directory; there is no separate frontend URL to open. The backend waits for the frontend's asset-ready check before starting.
Some services depend on your generator options: Stripe forwarding, MJML, and MinIO are included only when their corresponding options are enabled. An integration being present does not mean its credentials or production configuration are complete. Use Stripe test credentials for local payment work, never live credentials for an exploratory boot.
3) Open and inspect your app
With the default port settings:
- App:
http://localhost:8000 - Local email inbox:
http://localhost:8025
Check service status and the first failing service's logs before restarting:
docker compose -f docker-compose-local.yml ps
docker compose -f docker-compose-local.yml logs --tail=100 backend workers frontend
If the backend is still waiting for frontend readiness, inspect the frontend logs for dependency-install or asset-build errors. If the worker failed during initial Redis startup, confirm Redis is running, then recreate the worker:
make restart-worker
Check logs locally and redact secrets before sharing them. A healthy web page alone does not prove that a worker has completed a background job.
4) Run management commands
These Make targets run commands through the Dockerized backend:
make manage check
make manage migrate
make manage createsuperuser
make shell
The migration command is useful after model changes; initial startup already
runs migrations. make shell opens an interactive Django shell. The generated
Makefile also provides make test; see your repository's TECHNICAL.md for its
test dependencies and terminal-based development targets.
5) Check your first useful workflow
Before adding product features, verify:
- The homepage loads and CSS is present; there is no separate frontend port to visit.
- Sign up with a fresh test address, open the message in your local inbox, and enter its code in the same browser session. Reaching the code-entry screen is not proof that your app sent the message.
- The worker is running without repeated connection errors. When you add a background task, check the actual task result, not only the worker process. If it does not run, follow the Q2 worker troubleshooting guide to check the local service, broker, and queue configuration.
make manage checkcompletes without errors; investigate any warnings.
Code screen but no message? First check local mail capture.
If the plain test message arrives but the signup message does not, check the
template renderer before changing SMTP settings. Projects generated with
MJML render the signup email before handing it to Django’s mail backend.
In Compose, the backend uses MJML_URL=http://mjml:15500. If you run Django
on your host, start the generated services with make agent-services and set
MJML_URL=http://localhost:15500 for the Django process (substitute your
published LOCAL_MJML_PORT if you changed it). Restart Django after changing
its environment, then retry signup with a fresh test address. A code accepted
from the local inbox verifies this signup path, not production email delivery.
You do not need to queue another project in Djass to validate this app. Repository generation happens on hosted Djass before you download the ZIP. For your next step, use the first-feature workflow to define one user outcome and its acceptance checks. For authentication details, see the Django allauth guide.
Stop the local stack
When you finish development:
docker compose -f docker-compose-local.yml stop
This stops the services without deleting their data volumes. Use make serve
to start them again. Avoid volume-removal commands unless you intend to discard
the local data.
Command reference
The commands and service behavior above follow the bundled starter's
Makefile, docker-compose-local.yml, .env.example, and runtime pin files,
checked October 11, 2026. Your generated copies are the reference for your app;
this guide does not automatically update previously downloaded projects.
Prepare your first production release
When the app works locally, follow the first production deployment checklist to prepare an application image, HTTPS, email delivery and durable data, then verify the web and worker release before inviting users. Local development settings are not production credentials.