Docker Python Development & Debugging Guide

This guide outlines the setup for a lean, telemetry-free development environment using VSCodium, Docker, and tmux. It is designed to be consistent across Windows, Mac, and Linux.

1. Project Structure

Create the following files in your project root to keep the configuration modular and "neat".

.
├── .tmux.conf                # tmux customisation
├── .vscode/
│   ├── launch.json           # VSCodium debugger config
│   └── tasks.json            # Automation for tmux attach
├── docker-compose.yml        # Production base
├── docker-compose.override.yml # Development extensions
├── Dockerfile                # Image definition
└── main.py                   # Your application code

2. The Configuration Files

Dockerfile

Ensures all tools (tmux, debugpy) and system upgrades are baked into the image.

FROM python:3.10-slim

WORKDIR /usr/src/app

# System upgrades and tmux installation
RUN apt-get update && apt-get upgrade -y && \
    apt-get install -y tmux && \
    rm -rf /var/lib/apt/lists/*

# Upgrade pip and install requirements
COPY requirements.txt ./
RUN pip install --no-cache-dir --upgrade pip
RUN pip install --no-cache-dir -r requirements.txt debugpy

# Copy tmux config to root
COPY .tmux.conf /root/.tmux.conf

COPY . .

# Default production command
CMD [ "python", "./main.py" ]

docker-compose.yml (Production Base)

version: '3'
services:
  bank_analysis_excel:
    build: .
    container_name: bank_analysis_excel

docker-compose.override.yml (Development)

version: '3'
services:
  bank_analysis_excel:
    volumes:
      - .:/usr/src/app
    ports:
      - "5678:5678"
    tty: true
    stdin_open: true
    # Overrides the Dockerfile CMD to keep the workshop open
    command: tail -f /dev/null

.tmux.conf

Enables mouse support and customises the interface.

# Enable mouse mode for clicking/resizing
set -g mouse on

# Visual improvements
set -g default-terminal "screen-256color"
set -g history-limit 10000
set -g status-bg black
set -g status-fg white
set -g status-left ""
set -g status-right "#[fg=green]#H #[fg=white]%H:%M"

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Docker Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "${workspaceFolder}",
                    "remoteRoot": "/usr/src/app"
                }
            ]
        }
    ]
}

3. The Daily Workflow

Step 1: Start the Container

Run in your host terminal (PowerShell, bash, or zsh):

docker compose up -d

Step 2: Open VSCodium & Attach

If you set up the tasks.json automation, VSCodium will attach automatically. Otherwise, run:

docker compose exec bank_analysis_excel tmux

Step 3: Start the Persistent Loop

In your primary tmux pane, run this loop so the debugger is always ready:

while true; do python3 -m debugpy --listen 0.0.0.0:5678 --wait-for-client main.py; done

Step 4: Split and Work

Prefix Key: Ctrl + b
Split Vertically: Prefix then %
Switch Panes: Prefix then Arrow Keys (or just click with your mouse).

4. Deploying to Production

When the code is fixed and ready for a live environment:

Copy only docker-compose.yml, Dockerfile, and your code.
Do not copy docker-compose.override.yml.
Run docker compose up -d. The container will automatically execute main.py and close when finished.

3.7 KiB Raw Permalink Blame History