Skip to content

PyCharm Configuration for Containerized Development

Overview

When using containerized development mode, the app container exposes an SSH server on port 2222. This allows PyCharm to connect to the container as a remote interpreter, providing full IDE support including code completion, debugging, and run configurations.

Prerequisites

  • PyCharm Professional (remote interpreters are not available in the Community edition)
  • Containerized mode enabled (containerized = true in pyproject.toml)
  • The dev_tool running with the containers started (use "(Re)build the development environment" from the Home tab if this is your first time)

Step 1: Add the Remote Interpreter

  1. Open Settings (Ctrl + Alt + S)
  2. Navigate to Project: <project_name> > Python Interpreter
  3. Click Add Interpreter > On SSH...

SSH Connection

  1. Select New and enter the following connection details:

    Field Value
    Host localhost
    Port 2222
    Username stratus

  2. Click Next and enter the password: stratus

Note:

If PyCharm prompts you about a host key verification, click Yes to accept it. If you have previously connected and the container has been rebuilt, you may need to remove the old host key from your known_hosts file. See the Troubleshooting section below.

Python Environment

  1. Select Existing environment
  2. Set the interpreter type to Python
  3. Set the Python path to: /usr/local/bin/python3 (Python 3.11, system)
  4. Click Create to finish

Step 2: Create a Run Configuration

  1. Go to Run > Edit Configurations... (or click the configurations dropdown in the toolbar)
  2. Click the + button and select Python
  3. Configure the following settings:

General

Field Value
Name <project_name>
Python interpreter Select the SSH interpreter created in Step 1
Script manage.py
Script parameters runserver 0.0.0.0:8000

Working Directory

  1. Set the working directory to /app

Note:

This is the container path where your project is mounted, not the local path on your machine.

Environment Variables

  1. Click the ... button next to the Environment variables field

  2. Add the following variable:

    Name Value
    PYTHONUNBUFFERED 1

  3. Enable the Paths to ".env" files option and add the path to your local development.env file:

    C:/Users/<Username>/<path_to_project>/development.env

    Replace <Username> and <path_to_project> with the actual path on your machine.

  4. Click Apply and then OK

Step 3: Run the Server

  1. Select the run configuration you just created from the dropdown in the toolbar
  2. Click the Run button (or press Shift + F10)
  3. The Django development server will start inside the container and be accessible at http://localhost:8000

You can also use the Debug button (Shift + F9) to run the server with the PyCharm debugger attached, allowing you to set breakpoints and step through code.

Path Mappings

PyCharm should automatically detect the path mapping between your local project directory and the /app directory inside the container. If it does not, you can configure it manually:

  1. Open Settings > Project: <project_name> > Python Interpreter
  2. Click the gear icon next to the interpreter and select Edit...
  3. Expand SSH Interpreter and check the Path mappings section

  4. Add a mapping:

    Local Path Remote Path
    C:\Users\<Username>\<path_to_project> /app

Troubleshooting

Host Key Verification Failed

If you rebuild your containers, the SSH host keys will change and PyCharm may refuse to connect. To resolve this, remove the old entry from your known_hosts file:

  1. Open the file %USERPROFILE%\.ssh\known_hosts in a text editor
  2. Find and delete the line containing [localhost]:2222
  3. Save the file and try connecting again

Connection Refused on Port 2222

Ensure that the containers are running. Open the dev_tool and verify that the app container is active. If the containers are not running, use "(Re)build the development environment" from the Home tab to start them.

Interpreter Not Finding Packages

If PyCharm reports missing packages that are installed in the container, try the following:

  1. Open Settings > Project: <project_name> > Python Interpreter
  2. Click the reload icon to refresh the package list
  3. If packages are still missing, rebuild the container with the dev_tool to reinstall dependencies