Skip to content

Development Modes

Overview

The dev_tool supports two development modes: local and containerized. The mode is determined by the containerized setting in your project's pyproject.toml and controls how Django, PostgreSQL, and JavaScript tooling are executed.

Local Development

Local development is the default mode. Django runs directly on your machine using a virtual environment, while only PostgreSQL runs inside a Docker container.

How It Works

  • Python commands are executed using the virtual environment's interpreter (e.g., .venv_win/Scripts/python.exe on Windows).
  • Django management commands (e.g., migrate, runserver) run locally through the virtual environment.
  • PostgreSQL runs in a standalone Docker container managed by the dev_tool.
  • Bun commands (e.g., bun install, bun run build) execute directly on your host machine.
  • Package management is handled by uv (with pip as a fallback) inside the virtual environment.

Prerequisites

  • Python 3.11.9
  • Docker Desktop (for the PostgreSQL container)
  • Bun (if your project uses JavaScript tooling)
  • A virtual environment (created automatically by the dev_tool)

Configuration

Local mode is the default when containerized is not set or is set to false:

[tool.dev_tool]
port = 5745
single-instance = true

No additional configuration is required for local mode.

When to Use Local Mode

  • You prefer running Django directly on your machine.
  • You want faster iteration without container rebuild overhead.
  • Your project does not require a fully isolated environment.
  • You are working on a project that does not use JavaScript tooling through the dev_tool.

Containerized Development

Containerized development runs both Django and PostgreSQL inside Docker containers via docker-compose. This provides a fully isolated and reproducible environment.

How It Works

  • The dev_tool generates a docker-compose.yml from an internal template and starts two services: app (Django) and db (PostgreSQL).
  • Python and Django commands are executed inside the app container using docker exec.
  • Bun commands also run inside the app container, so Bun does not need to be installed on your host machine.
  • Dependencies (Python and JavaScript) are installed inside the container automatically when the environment is built or rebuilt.
  • The project directory is mounted into the container at /app, so code changes are reflected immediately.
  • An SSH server runs inside the app container on port 2222, enabling remote interpreter support in IDEs like PyCharm.

Prerequisites

  • Docker Desktop

Note:

In containerized mode, you do not need Python, Bun, or a virtual environment installed on your host machine. Everything runs inside the container.

Configuration

Enable containerized mode by adding containerized = true to the [tool.dev_tool] section of your pyproject.toml:

[tool.dev_tool]
containerized = true
port = 5745
single-instance = true

Container Architecture

The docker-compose.yml template defines two services:

Service Container Name Description
db <project>-db PostgreSQL database with a health check and persistent volume.
app <project>-app Application container with Django, Bun, and SSH access.

The following ports are exposed by default:

Port Purpose
8000 Django development server
2222 SSH access (for remote interpreters)
DATABASE_PORT PostgreSQL (configured in development.env)

Volumes

Volume Purpose
<project>-postgres-database Persistent PostgreSQL data
<project>-site-packages Cached Python site-packages
<project>-ssh-host-keys Persistent SSH host keys

Switching Between Modes

To switch from local to containerized mode (or vice versa):

  1. Update the containerized setting in your pyproject.toml
  2. Restart the dev_tool
  3. Run (Re)build the development environment from the Home tab

The dev_tool will automatically stop any conflicting containers when switching modes. When switching to containerized mode, it will build the required Docker images and start the services. When switching to local mode, it will stop compose services and fall back to the standalone PostgreSQL container.

When to Use Containerized Mode

  • You want a fully isolated and reproducible development environment.
  • You are working on a project that uses JavaScript tooling (the JavaScript tab in the dev_tool is only available in containerized mode).
  • You want to avoid installing Python, Bun, or other dependencies on your host machine.
  • You need SSH-based remote interpreter support for your IDE.

Comparison

Feature Local Containerized
Django execution Virtual environment on host Inside Docker container
PostgreSQL Standalone Docker container Docker Compose service
Bun / JavaScript Runs on host (requires Bun installed) Runs inside container
Virtual environment required Yes No
Docker Desktop required Yes Yes
JavaScript tab in dev_tool No Yes
SSH remote interpreter No Yes (port 2222)
Parallel development support Via PYTHONPATH_APPEND Via PYTHONPATH_APPEND (mounted as volumes)
Rebuild overhead Minimal Requires image rebuild on dependency changes