PyCharm Pro: как запустить удалённый Docker Compose по SSH

Настроить PyCharm Professional для удалённого запуска Docker Compose по SSH реально: создайте SSH‑подключение к Docker в Settings → Build, Execution, Deployment → Docker, в Run Configuration типа Docker‑Compose укажите путь к docker‑compose.yml на удалённом сервере, в Before launch добавьте выполнение git pull (через SSH) и затем команду docker compose up -d --build. Частая причина, почему docker compose не стартует и видны Windows‑пути — PyCharm использует локальный (Windows) путь вместо удалённого: решается выбором compose‑файла на хосте или корректной настройкой Deployment / Path mappings. После этого контейнеры и логи будут доступны через окно Services/Docker в IDE.

Содержание

• Настройка Docker remote в PyCharm (SSH)
• Run configuration: git pull → docker compose up -d --build
• Почему PyCharm отправляет Windows‑пути и как использовать относительные пути
• Поля и параметры, которые нужно проверить (чек‑лист)
• Примеры корректных конфигураций (конкретные значения)
• Отладка: как проверить контейнеры и логи и найти причину ошибки
• Источники
• Заключение

Настройка Docker remote в PyCharm (SSH)

Коротко — нужно создать Docker‑connection по SSH и убедиться, что PyCharm видит docker/compose на удалённом хосте.

Шаги (пошагово)

• Откройте Settings → Build, Execution, Deployment → Docker → нажмите «+».
• Выберите тип подключения SSH (или «Docker via SSH») и укажите Docker host как ssh://user@host:22 (или через UI введите хост, порт, имя пользователя и ключ).
• Аутентификация: лучше всего — SSH‑ключ (OpenSSH), либо агент. Нажмите Test Connection — IDE должна вернуть информацию о Docker Engine.
• Проверьте, что на сервере доступны команды: docker --version и docker compose version (или docker‑compose --version). Если команды отсутствуют — установите Docker/Compose на сервере.

Почему это важно? PyCharm вызывает docker и docker compose на том хосте, к которому вы подключились, поэтому окружение (PATH, права, версия compose) должно быть валидным для пользователя, под которым идёт SSH‑подключение. Официальное описание этой логики есть в документации JetBrains: PyCharm — Using Docker as a remote interpreter.

Run configuration: git pull → docker compose up -d --build

Цель: при нажатии Run в IDE последовательно выполнить git pull на сервере, затем docker compose up -d --build — и всё это отработает на удалённом хосте.

Как собрать конфигурацию

1. Run → Edit Configurations → «+» → Docker‑Compose.
2. Параметры конфигурации (основные):

• Server: выберите Docker SSH connection, который вы создали в предыдущем разделе.
• Compose files: укажите путь к docker‑compose.yml на удалённом сервере (не локальный Windows‑путь). В документации JetBrains прямо рекомендовано указывать путь compose‑файла на удалённом хосте — тогда PyCharm будет работать с ним на сервере.
• Working directory: укажите удалённую директорию проекта (например, /home/deploy/project).
• Command: up
• Options: -d --build

3. Before launch (очень важно — порядок):

• 1-й шаг: выполнить git pull на удалённом сервере. Практично: добавить External Tool или простой вызов ssh из «Before launch»:
• Пример команды (как External Tool или shell):
  ssh -i ~/.ssh/id_rsa deploy@server ‘cd /home/deploy/project && git pull’
• Убедитесь, что ключи/доступ настроены и git pull не требует интерактивного ввода пароля.
• 2-й шаг (опционально, когда вы используете локальные изменения): «Upload to » — если вы храните изменения локально и хотите их загрузить вместо git pull.
• 3-й шаг: сам Docker‑Compose запуск (внутри Run Configuration).

Почему git pull должен быть на сервере? Если сборка (build context) в compose использует локальные файлы, docker на сервере должен видеть эти файлы. Либо вы актуализируете код через git pull, либо загружаете файлы перед запуском.

Совет: можно отдельно создать External Tool в Settings → Tools → External Tools, чтобы переиспользовать шаг git pull в разных конфигурациях.

Почему PyCharm отправляет Windows‑пути и как использовать относительные пути из compose‑файла

Что обычно происходит? PyCharm умеет подставлять абсолютные пути из вашей локальной машины при развертывании. Если в Run Configuration выбран локальный compose‑файл или отсутствуют правильные маппинги, IDE может преобразовать относительные пути в абсолютные Windows‑пути (например, C:\Users…), и docker на Linux увидит некорректные пути — контейнеры не поднимаются.

Как исправить (варианты)

• Самый надёжный: в конфигурации Docker‑Compose указывайте compose‑файл именно на удалённом хосте (удалённый путь вроде /home/deploy/project/docker-compose.yml). Тогда относительные пути внутри compose будут резолвиться уже на сервере.
• Если вы хотите, чтобы PyCharm переводил локальные пути в удалённые — настройте Deployment → SFTP и Mapping:
• Settings → Build, Execution, Deployment → Deployment → добавьте SFTP сервер, в Mapping укажите Local path = C:\path\to\project, Deployment path = /home/deploy/project. Пометьте этот сервер как Default для проекта. PyCharm будет знать, как конвертировать пути.
• Проверьте поле Working directory в Docker‑Compose run configuration — оно должно быть удалённым путём к корневой папке проекта на сервере.
• Проверяйте результат: на сервере выполните:
  ssh deploy@server ‘cd /home/deploy/project && docker compose -f docker-compose.yml config’
  Эта команда покажет окончательную конфигурацию Compose; если вы видите пути вида C:\… — значит PyCharm всё ещё передаёт Windows‑пути.

Коротко: либо используйте compose‑файл на сервере, либо корректно настройте Deployment/Path mappings, чтобы IDE знала соответствие локальных и удалённых путей.

Поля и параметры, которые нужно проверить (чек‑лист)

Проверьте и согласуйте эти поля:

• Docker connection (Settings → Build, Execution, Deployment → Docker):
• Connection type: SSH, Docker host = ssh://user@host:22, Test Connection — OK.
• Compose files (в Run Configuration):
• Указан путь на удалённом хосте: /home/user/project/docker-compose.yml.
• Working directory (Run Configuration):
• /home/user/project — важен для корректного резолвинга относительных volume/context.
• Path mappings / Deployment:
• Settings → Build, Execution, Deployment → Deployment → Mappings: локальный путь → удалённый путь.
• Отметьте сервер по умолчанию, при необходимости включите авто‑загрузку.
• Pre‑run steps:
• SSH git pull → убедиться, что выполняется в той же папке, где лежит docker‑compose.yml.
• Если используете Upload, поставьте Upload перед запуском compose.
• Права пользователя:
• Пользователь SSH должен быть в группе docker (или иметь sudo без пароля для docker), иначе docker команды будут падать с ошибкой доступа.
• Compose binary и PATH:
• В неинтерактивной SSH‑сессии PATH может отличаться. Проверьте: ssh user@host ‘echo $PATH; which docker; docker compose version’.
• При необходимости используйте полный путь к docker или поправьте PATH для SSH‑сессий.
• Compose версия:
• docker compose (v2) vs docker‑compose (v1) — убедитесь, что версия поддерживается вашей версией PyCharm.

Полезные тест‑команды

• Проверка docker на сервере: ssh deploy@server ‘docker --version; docker compose version || docker-compose --version’
• Проверка resolved compose: ssh deploy@server ‘cd /home/deploy/project && docker compose -f docker-compose.yml config’
• Ручной запуск для отладки: ssh deploy@server ‘cd /home/deploy/project && docker compose up -d --build’ — если это не работает руками, проблема не в PyCharm.

Примеры корректных конфигураций (конкретные значения)

Пример: предположим, что локальный проект в C:\Users\you\project, а на сервере /home/deploy/project, пользователь deploy, ключ ~/.ssh/id_rsa.

1. Docker connection:

• Docker host: ssh://deploy@1.2.3.4:22
• Auth: Key pair (OpenSSH) → путь к приватному ключу (или агент).

2. Deployment (SFTP):

• Host: 1.2.3.4, User: deploy, Root path: /home/deploy/project
• Mappings: Local path = C:\Users\you\project → Deployment path = /home/deploy/project

3. Run Configuration: Docker‑Compose

• Name: Remote: up (compose)
• Server: ssh://deploy@1.2.3.4:22 (ваш Docker connection)
• Compose files: /home/deploy/project/docker-compose.yml (choose file on remote host)
• Working directory: /home/deploy/project
• Command: up
• Options: -d --build

4. Before launch:

• • External Tool (ssh): Program = ssh, Parameters = -i ~/.ssh/id_rsa deploy@1.2.3.4 “cd /home/deploy/project && git pull”
• (Опционально) + Upload to ‘deploy’ — если правите файлы локально и хотите загрузить их.

Пример docker-compose.yml (корректные относительные пути):

version: "3.8"
services:
 web:
 build:
 context: .
 dockerfile: Dockerfile
 volumes:
 - ./app:/app # относительный путь, будет резолвиться на сервере
 ports:
 - "8000:8000"

Проверка перед нажатием Run:

• ssh deploy@1.2.3.4 ‘cd /home/deploy/project && git status --porcelain && docker compose -f docker-compose.yml config’

Отладка: как проверить контейнеры и логи и найти причину ошибки

1. Логи PyCharm:

• Help → Show Log in Explorer (или Console) — ищите команды, которые IDE посылает на сервер; это покажет, какие пути и команды реально выполнены.

2. Docker / Containers в IDE:

• View → Tool Windows → Services (или Docker). Вы увидите подключение к удалённому Docker, список контейнеров. Правый клик → Show Logs / Attach Console / Exec.

3. На сервере:

• docker compose ps
• docker compose logs -f
• docker compose -f docker-compose.yml config (показывает как compose резолвит volumes/paths — самый частый индикатор неправильных путей).

4. Типичные ошибки и как их распознавать:

• Permission denied to Docker socket → пользователь не в группе docker. Решение: sudo usermod -aG docker user && перезапустить сессию.
• Command not found: docker / docker compose → PATH в неинтерактивной сессии не содержит пути к бинарям. Решение: поправить /etc/profile или использовать абсолютный путь.
• Volume mount error / host path not found → compose получил Windows‑путь; проверьте, что compose‑файл выбран на сервере или правильны mappings.

5. Дополнительный трюк:

• В Before launch можно добавить диагностическую команду типа ssh deploy@server ‘pwd; ls -la; docker --version; docker compose version’ — это быстро покажет окружение, в котором будет работать compose.

Источники

• Официальная документация PyCharm: Using Docker as a remote interpreter — настройка Docker/Compose через SSH и упоминание path mappings.
• Данные Yandex Wordstat (ключевые слова/семантика): https://wordstat.yandex.ru — использованы для SEO‑подбора ключевых фраз (PyCharm, Docker Compose, удалённый и т.д.).
• Практические руководства по удалённой разработке и SSH в PyCharm: https://genmind.ch/posts/Code-from-Anywhere-Your-SSH-Guide-to-Remote-Development-in-PyCharm/
• Пример деплоя на удалённый Docker с docker‑compose: https://claytoy.com/blog/how-to-deploy-on-remote-docker-hosts-with-docker-compose/
• Community‑issue о взаимодействии docker compose и клиентских вызовов: https://github.com/docker/compose/issues/12505

Заключение

Коротко: настройте Docker‑подключение по SSH, укажите в Docker‑Compose конфигурации путь к compose‑файлу на удалённом хосте, добавьте pre‑launch шаг git pull (через ssh) и, при необходимости, Upload to deployment. Основная причина появления Windows‑путей — использование локального compose‑файла или отсутствие корректных Deployment/Path mappings; исправляйте это выбором удалённого файла или настройкой маппингов. Проверьте доступность docker/compose в non‑interactive SSH, права пользователя и выполните команды диагностики (docker compose config, docker compose ps, logs). Если хотите, подготовлю готовый файл шаг‑за‑шаг (скриншоты/точные значения полей для вашей версии PyCharm) — пришлите текущие значения Docker connection, путь проекта и пример docker‑compose.yml.