Перейти к основному содержимому

Разработка с Dev Containers

Dev Containers обеспечивают стабильную, воспроизводимую среду разработки с использованием Docker-контейнеров. Всего одним кликом вы можете начать работу с средой разработки Immich на Mac, Linux, Windows или в облаке с использованием GitHub Codespaces.

Начните быстро!

Открыть в GitHub Codespaces

Узнать больше о Dev Containers

Предварительные требования​

Перед началом работы убедитесь, что у вас есть:

  • Docker Desktop (последняя версия)
  • Visual Studio Code с расширением Dev Containers
  • Git для клонирования репозитория
  • Минимум 8GB RAM (рекомендуется 16GB)
  • 20GB свободного места на диске
Альтернативные среды разработки

Хотя это руководство сосредоточено на VS Code, у вас есть множество вариантов для разработки с Dev Containers:

Локальные редакторы:

  • IntelliJ IDEA - Полная поддержка JetBrains IDE
  • neovim - Лёгкий редактор на основе терминала
  • Emacs - Расширяемый текстовый редактор
  • DevContainer CLI - Интерфейс командной строки

Облачные решения:

  • GitHub Codespaces - Полностью интегрированный с GitHub, отличная поддержка devcontainer.json
  • GitPod - SaaS-платформа с поддержкой Dev Containers (ранее использовала gitpod.yml)

Собственные решения:

  • Coder - Ориентирован на корпоративное использование, требуется знание Terraform, самоуправляемый
  • DevPod - Инструмент только для клиента с отличной поддержкой devcontainer.json, работает с любым провайдером (локальным, облачным или на месте)

Сервисы Dev Container​

Среда Dev Container состоит из следующих сервисов:

СервисИмя контейнераОписаниеПорты
Сервер и Вебimmich-serverЗапускает API сервер и веб-фронтенд в режиме разработки2283 (API)
3000 (Веб)
9230 (Отладка воркеров)
9231 (Отладка API)
База данныхdatabaseБаза данных PostgreSQL5432
КэшredisСервер кэша Valkey6379
Машинное обучениеimmich-machine-learningСервер вывода моделей ML для Immich3003

Начало работы​

Шаг 1: Клонировать репозиторий​

git clone https://github.com/immich-app/immich.git
cd immich

Шаг 2: Настроить переменные окружения​

Dev контейнеры Immich считывают переменные окружения из вашей оболочки, а не из файлов .env. Это позволяет им работать в облачных средах без предварительной настройки.

Конфигурация

При запуске локально, если вы хотите создать (или использовать существующую) папку для базы данных и/или хранения фотографий, необходимо установить переменную UPLOAD_LOCATION в оболочке перед запуском Dev Container. Это определяет, где будут храниться загруженные файлы и данные базы данных.

# Временно для текущей сессии
export UPLOAD_LOCATION=/opt/dev_upload_folder

# Или добавить в профиль оболочки для постоянного использования
# (~/.bashrc, ~/.zshrc, ~/.bash_profile и т.д.)
echo 'export UPLOAD_LOCATION=/opt/dev_upload_folder' >> ~/.bashrc
source ~/.bashrc

Шаг 3: Запустить Dev Container​

совет

Разработка Immich активно использует специализированные основные образы для разработки на основе docker-compose. Поэтому вы не сможете использовать команду Clone Repository in a Container Volume в VSCode.

С использованием интерфейса VS Code:​

  1. Откройте клонированный репозиторий в VS Code
  2. Нажмите F1 или Ctrl/Cmd+Shift+P, чтобы открыть палитру команд
  3. Введите и выберите "Dev Containers: Rebuild and Reopen in Container"
  4. Выберите "Immich - Backend, Frontend and ML" из списка
  5. Подождите, пока контейнер создастся и запустится (это может занять несколько минут при первом запуске)

Использование быстрых действий VS Code:​

  1. Откройте репозиторий в VS Code
  2. Вы увидите всплывающее окно, предлагающее открыть в контейнере
  3. Нажмите "Reopen in Container"

Использование командной строки:​

# С использованием DevContainer CLI
devcontainer up --workspace-folder .

Детали переменных окружения​

Как Dev Containers обрабатывают переменные окружения​

В отличие от установки для разработчиков Immich на основе Docker Compose, которая использует файлы .env, Dev контейнеры Immich считывают переменные окружения из вашей оболочки. Это настроено в .devcontainer/devcontainer.json:

"remoteEnv": {
    "UPLOAD_LOCATION": "${localEnv:UPLOAD_LOCATION:./Library}",
    "DB_PASSWORD": "${localEnv:DB_PASSWORD:postgres}",
    "DB_USERNAME": "${localEnv:DB_USERNAME:postgres}",
    "DB_DATABASE_NAME": "${localEnv:DB_DATABASE_NAME:immich}"
}

Синтаксис ${localEnv:VARIABLE:default} считывает значения из вашей оболочки с опциональными значениями по умолчанию.

Разрешение пути для загрузок​

Переменная окружения UPLOAD_LOCATION управляет, где будут храниться файлы:

По умолчанию: ./Library (относительно директории docker) Рекомендуемый путь: <immich-root>/docker/Library

Созданные привязки:

# Из .devcontainer/server/container-compose-overrides.yml
- ${UPLOAD_LOCATION-./Library}/photos:/workspaces/immich/server/upload
- ${UPLOAD_LOCATION-./Library}/postgres:/var/lib/postgresql/data

Конфигурация базы данных​

Эти переменные имеют разумные значения по умолчанию (для разработки), но могут быть настроены:

ПеременнаяПо умолчаниюОписание
DB_PASSWORDpostgresПароль PostgreSQL
DB_USERNAMEpostgresИмя пользователя PostgreSQL
DB_DATABASE_NAMEimmichИмя базы данных

Установка переменных окружения​

Добавьте их в профиль вашей оболочки (~/.bashrc, ~/.zshrc, ~/.bash_profile и т.д.):

# Обязательно
export UPLOAD_LOCATION=./Library  # или абсолютный путь

# Опционально (только если используются не стандартные значения)
export DB_PASSWORD=your_password
export DB_USERNAME=your_username
export DB_DATABASE_NAME=your_database

Не забудьте перезагрузить конфигурацию оболочки:

source ~/.bashrc  # или ~/.zshrc и т.д.

Конфигурация Git​

SSH-ключи и аутентификация​

Чтобы использовать ваши SSH-ключи для доступа к GitHub внутри Dev контейнера:

  1. Запустите SSH агент на вашем компьютере:

    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa  # или путь к вашему ключу

  2. VS Code автоматически перенаправляет ваш SSH агент в контейнер

Для подробных инструкций смотрите руководство VS Code по совместному использованию Git-акредитивов.

Подписание коммитов​

Чтобы использовать ваш SSH-ключ для подписания коммитов, смотрите руководство GitHub по SSH подписанию коммитов.

Рабочий процесс разработки​

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

Когда Dev контейнер запускается, он автоматически:

  1. Запускает скрипт post-create (container-server-post-create.sh):

    • Регулирует права доступа для пользователя node
    • Устанавливает зависимости: npm install для всех пакетов
    • Сборка TypeScript SDK: npm run build в open-api/typescript-sdk

  2. Запускает серверы разработки через задачи VS Code:

    • Immich API Server (Nest) - сервер API с hot-reloading на порту 2283
    • Immich Web Server (Vite) - веб-фронтенд с hot-reloading на порту 3000
    • Оба сервера отслеживают изменения файлов и автоматически перекомпилируются

  3. Настраивает переадресацию портов:

информация

Настройка Dev контейнера заменяет команду make dev из традиционной настройки. Все сервисы запускаются автоматически при открытии контейнера.

Доступ к сервисам​

После запуска вы можете получить доступ:

СервисURLОписание
Веб-интерфейсhttp://localhost:3000Основной веб-интерфейс
APIhttp://localhost:2283REST API точки (не используется напрямую, веб-интерфейс предоставляет это через http://localhost:3000/api)
База данныхlocalhost:5432PostgreSQL (имя пользователя: postgres) (не используется напрямую)

Подключение мобильных приложений​

Для подключения мобильного приложения к вашему Dev контейнеру:

  1. Найдите IP-адрес вашего компьютера
  2. В мобильном приложении используйте: http://YOUR_IP:3000/api
  3. Убедитесь, что ваш брандмауэр разрешает подключения на порт 2283

Внесение изменений в код​

  • Код сервера (/server): изменения вызывают автоматический перезапуск
  • Веб-код (/web): изменения вызывают горячую замену модулей
  • Миграции базы данных: Выполните команду npm run sync:sql в директории сервера
  • Изменения API: Перегенерируйте TypeScript SDK с помощью make open-api

Тестирование​

Запуск тестов​

Dev Container поддерживает несколько способов запуска тестов:

Использование команд Make (рекомендуется)​

# Запуск тестов для конкретных компонентов
make test-server         # Модульные тесты сервера
make test-web           # Модульные тесты веб-приложения
make test-e2e           # Сквозные тесты
make test-cli           # Тесты CLI

# Запуск всех тестов
make test-all           # Запускает тесты для всех компонентов

# Интеграционные тесты
make test-medium-dev    # Сквозные тесты

Прямое использование NPM​

# Тесты сервера
cd /workspaces/immich/server
npm test                # Запуск всех тестов
npm run test:watch     # Режим наблюдения
npm run test:cov       # Отчет о покрытии кода

# Тесты веб-приложения
cd /workspaces/immich/web
npm test               # Запуск всех тестов
npm run test:watch     # Режим наблюдения

# Сквозные тесты
cd /workspaces/immich/e2e
npm run test           # Запуск тестов API
npm run test:web       # Запуск тестов веб-интерфейса

Команды для проверки качества кода​

# Линтинг
make lint-server        # Проверка кода сервера
make lint-web          # Проверка кода веб-приложения
make lint-all          # Проверка всех компонентов

# Форматирование
make format-server      # Форматирование кода сервера
make format-web        # Форматирование кода веб-приложения
make format-all        # Форматирование всех компонентов

# Проверка типов
make check-server       # Проверка типов для сервера
make check-web         # Проверка типов для веб-приложения
make check-all         # Проверка всех компонентов

# Комплексная проверка качества
make hygiene-all       # Выполняет линтинг, форматирование, проверку типов, синхронизацию SQL и аудит

Дополнительные команды Make​

# Команды сборки
make build-server       # Сборка сервера
make build-web         # Сборка веб-приложения
make build-all         # Сборка всех компонентов

# Генерация API
make open-api          # Генерация спецификации OpenAPI
make open-api-typescript # Генерация TypeScript SDK
make open-api-dart     # Генерация Dart SDK

# База данных
make sql               # Синхронизация схемы базы данных

# Зависимости
make install-server    # Установка зависимостей сервера
make install-web      # Установка зависимостей веб-приложения
make install-all      # Установка всех зависимостей

Отладка​

Dev Container предварительно настроен для отладки:

  1. Отладка API-сервера:

    • Установите точки останова в VS Code
    • Нажмите F5 или используйте панель "Run and Debug"
    • Выберите конфигурацию "Attach to Server"
    • Порт отладки: 9231

  2. Отладка рабочих процессов:

    • Используйте конфигурацию "Attach to Workers"
    • Порт отладки: 9230

  3. Отладка веб-приложения:

    • Используйте инструменты разработчика браузера
    • Поддерживаются расширения для отладки в Chrome/Edge внутри VS Code

Решение проблем​

Общие проблемы​

Ошибки прав​

Проблема: ошибки EACCES или отказано в доступе
Решение:

  • Dev Container работает от имени пользователя node (UID 1000)
  • Если ваш UID отличается, могут возникнуть проблемы с правами
  • Попробуйте пересобрать контейнер: "Dev Containers: Rebuild Container"

Контейнер не запускается​

Проблема: Dev Container не удалось запустить или собрать
Решение:

  1. Убедитесь, что Docker работает: docker ps
  2. Очистите ресурсы Docker: docker system prune -a
  3. Проверьте доступное место на диске
  4. Убедитесь, что лимиты ресурсов Docker Desktop установлены корректно

Порт уже используется​

Проблема: "Порт 3000/2283 уже используется"
Решение:

  1. Проверьте конфликтующие сервисы: lsof -i :3000 (macOS/Linux)
  2. Остановите конфликтующие сервисы или измените настройки портов
  3. Перезапустите Docker Desktop

Местоположение загрузки не установлено​

Проблема: ошибки, связанные с отсутствием UPLOAD_LOCATION
Решение:

  1. Установите переменную окружения: export UPLOAD_LOCATION=./Library
  2. Добавьте переменную в профиль вашей оболочки для постоянного использования
  3. Перезапустите терминал и VS Code

Сбой подключения к базе данных​

Проблема: не удается подключиться к PostgreSQL
Решение:

  1. Убедитесь, что все контейнеры работают: docker ps
  2. Проверьте логи: "Dev Containers: Show Container Log"
  3. Убедитесь, что учетные данные базы данных соответствуют переменным окружения

Получение помощи​

Если вы столкнулись с проблемами:

  1. Проверьте логи контейнера: View → Output → Выберите "Dev Containers"
  2. Пересоберите контейнер без использования кеша: "Dev Containers: Rebuild Container Without Cache"
  3. Ознакомьтесь с распространенными проблемами Docker
  4. Задайте вопросы в Discord на канале #help-desk-support

Разработка мобильных приложений​

Хотя Dev Container в основном предназначен для разработки сервера и веб-приложений, вы можете подключить мобильные приложения для тестирования:

Подключение приложений для iOS/Android​

  1. Убедитесь, что API доступен:

    # Найдите IP вашего устройства
    # macOS
    ipconfig getifaddr en0
    # Linux
    hostname -I
    # Windows (в WSL2)
    ip addr show eth0

  2. Настройте мобильное приложение:

    • URL сервера: http://YOUR_IP:2283/api
    • Убедитесь, что брандмауэр разрешает использование порта 2283

  3. Для разработки мобильных приложений ознакомьтесь с руководством по разработке мобильных приложений, которое включает:

    • Настройку Flutter
    • Запуск на симуляторах/устройствах
    • Отладку, специфичную для мобильных приложений

Расширенная конфигурация​

Пользовательские расширения VS Code​

Добавьте расширения в файл .devcontainer/devcontainer.json:

"customizations": {
  "vscode": {
    "extensions": [
      "your.extension-id"
    ]
  }
}

Дополнительные сервисы​

Чтобы добавить сервисы (например, Redis Commander), модифицируйте:

  1. /docker/docker-compose.dev.yml - Добавьте определение сервиса
  2. /.devcontainer/server/container-compose-overrides.yml - Добавьте необходимые переопределения

Ограничения ресурсов​

Настройте ресурсы Docker Desktop:

  • macOS/Windows: Docker Desktop → Настройки → Ресурсы
  • Linux: Измените конфигурацию демона Docker

Рекомендуемые минимальные параметры:

  • CPU: 4 ядра
  • Оперативная память: 8GB
  • Диск: 20GB

Следующие шаги​