Работа в Dev Containers¶

Dev Containers — это спецификация containers.dev, а её основной файл — devcontainer.json. Он описывает, как собрать среду разработки в контейнере: какой образ использовать, какие инструменты и расширения ставить.

Главное правило: Koda работает там же, где находится проект, — то есть внутри контейнера. Команды, чтение и запись файлов, поиск, индексация и настройки выполняются на стороне контейнера.

Как это устроено¶

Что нужно сделать¶

1. Установить и настроить Docker на своём компьютере — см. раздел Подготовка Docker.
2. Открыть проект в контейнере — см. раздел Открытие проекта.
3. Установить Koda в контейнер, а не только на свой компьютер — см. раздел Установка Koda.
4. Войти в аккаунт — так же, как при обычной работе.
5. Убедиться, что изнутри контейнера доступен api.kodacode.ru — см. раздел Сеть.
6. При необходимости сохранить настройки и индекс между пересозданиями контейнера — см. раздел Настройки.

Подготовка Docker¶

Dev Containers собирает и запускает контейнеры через Docker, поэтому сначала установите и настройте Docker на своём компьютере.

• Windows — Docker Desktop 2.0 и выше на Windows 10 Pro и Enterprise. На Windows 10 Home (2004 и выше) нужен Docker Desktop 2.3 и выше с бэкендом WSL 2: в настройках Docker включите Use the WSL 2 based engine и убедитесь, что ваш дистрибутив добавлен в Resources → WSL Integration.
• macOS — Docker Desktop 2.0 и выше.

• Linux — Docker CE/EE 18.06 и выше и Docker Compose 1.21 и выше. Добавьте пользователя в группу docker и перезайдите в систему:

  sudo usermod -aG docker $USER
  

  Пакет Docker из Ubuntu Snap не поддерживается — ставьте Docker из официального репозитория.

Контейнеры, с которыми работает Dev Containers: Debian 9 и выше, Ubuntu 16.04 и выше, CentOS и RHEL 7 и выше (архитектуры x86_64, ARMv7l, ARMv8l) или Alpine Linux 3.9 и выше (x86_64). Другие Linux-контейнеры на базе glibc обычно тоже подходят.

Открытие проекта¶

Установка Koda¶

Общая инструкция по установке — на странице Установка плагина.

Автоматическая настройка¶

Через devcontainer.json можно заранее описать всё нужное для работы Koda, чтобы при каждом создании контейнера это настраивалось само.

Установить расширение Koda в контейнер:

{
  "customizations": {
    "vscode": {
      "extensions": ["Koda.koda"]
    }
  }
}

Установить плагин Koda в бэкенд JetBrains:

{
  "customizations": {
    "jetbrains": {
      "plugins": ["Koda"]
    }
  }
}

Установить ripgrep для быстрого поиска по содержимому:

{
  "postCreateCommand": "sudo apt-get update && sudo apt-get install -y ripgrep"
}

Сохранить настройки и индекс Koda между пересозданиями контейнера — вынести каталог ~/.koda в отдельный том:

{
  "mounts": [
    { "source": "koda-home", "target": "/home/vscode/.koda", "type": "volume" }
  ]
}

Добавить готовые наборы установки через Features — например, GitHub CLI:

{
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  }
}

Features берутся из общего каталога containers.dev и описывают установку инструментов, сред выполнения и библиотек.

Задать настройки, которые действуют только внутри контейнера:

{
  "customizations": {
    "vscode": {
      "settings": {
        "editor.formatOnSave": true
      }
    }
  }
}

Файлы, пути и терминал¶

Koda работает с файлами проекта напрямую, поэтому пути указываются так, как они выглядят в контейнере.

• Относительные пути (например, src/index.ts) ищутся в корне проекта.
• Абсолютные пути внутри контейнера (например, /workspaces/my-app) разрешаются в файловой системе контейнера.

Команды выполняются в терминале на стороне контейнера.

• Команды работают в том же окружении, что и проект, поэтому доступны все установленные в контейнере утилиты.
• Терминал Koda переиспользуется: если команда активировала виртуальное окружение или изменила переменные, это сохраняется между вызовами.
• Команды можно останавливать — Koda прерывает их и при необходимости закрывает терминал.
• Слишком большой вывод команды сокращается до 2000 строк или 50 КиБ, а полный текст сохраняется в файл — см. «Большой вывод инструментов».

Поиск по коду¶

Поиск файлов по имени учитывает правила .gitignore и .kodaignore.

Индексация¶

Данные индексации хранятся на стороне контейнера, в каталоге ~/.koda/index внутри контейнера.

• Впервые открыв проект в контейнере, Koda построит индекс заново.
• Если контейнер пересоздаётся, каталог ~/.koda может быть потерян вместе с индексом — тогда проект нужно проиндексировать повторно.
• Чтобы сохранить индекс между пересозданиями, вынесите ~/.koda в отдельный том — см. раздел Автоматическая настройка.

Индексация включается на вкладке Индексация в настройках — см. Настройки индексации. Подробнее о решении проблем с индексацией — на странице Индексация.

Настройки¶

В контейнере Koda читает настройки со стороны контейнера — как если бы она была запущена в этой системе.

• Глобальный файл config.yaml лежит в ~/.koda/config.yaml внутри контейнера, а не в ~/.koda вашей системы.
• Проектный файл .kodarc.json — в корне проекта внутри контейнера.
• Правила из файла .kodarules и игноры из .kodaignore — также в корне проекта в контейнере.
• Локальные навыки из .koda/skills, .claude/skills и .agents/skills ищутся относительно корня проекта в контейнере.

Сеть¶

Запросы к моделям Koda выполняет та же сторона, где работает Koda, — то есть контейнер.

• Изнутри контейнера должен быть доступен api.kodacode.ru.
• Учитывайте ограничения сети контейнера: при закрытой сети запросы к моделям не пройдут.
• Если вы используете прокси или VPN, настройте их доступность и внутри контейнера.
• Если приложению внутри контейнера нужно принимать подключения с вашего компьютера, опубликуйте или пробросьте порт: свойство forwardPorts в devcontainer.json либо команда Forward a Port.

Управление контейнерами¶

Типичные проблемы¶

Koda не видит файлы проекта¶

Убедитесь, что Koda установлена в контейнер, а проект открыт в контейнере. Проверьте, что папка проекта действительно открыта как рабочая область.

Команды выполняются не там, где ожидается¶

Команды всегда выполняются на стороне контейнера. Если вы ожидали команды на своём компьютере, откройте проект локально.

Поиск по содержимому ничего не находит¶

Проверьте, установлен ли ripgrep или grep внутри контейнера. Также убедитесь, что искомый текст не исключён правилами .gitignore или .kodaignore.

После пересоздания контейнера пропали настройки или индекс¶

Каталог ~/.koda внутри контейнера не сохраняется между пересозданиями. Вынесите его в отдельный том через mounts в devcontainer.json — см. раздел Автоматическая настройка.

Koda не отвечает¶

Проверьте, что изнутри контейнера есть доступ к api.kodacode.ru — см. раздел Сеть. Если вы используете прокси или VPN, они тоже должны быть доступны внутри контейнера.

Контейнер на Alpine: часть расширений не работает¶

В контейнерах на Alpine Linux некоторые расширения могут не работать из-за зависимости от glibc в нативном коде. Если это мешает, используйте образ на базе Debian или Ubuntu.

Образы Windows-контейнеров не поддерживаются¶

Dev Containers работает только с Linux-контейнерами. Образы Windows-контейнеров и Docker Toolbox не поддерживаются. Пакет Docker из Ubuntu Snap тоже не поддерживается — ставьте Docker из официального репозитория.