Documentation navigation

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 check completes 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.