mt5-manager/docs/installation.md

# Установка и первый запуск

[Документация](README.md) · [Настройки](configuration.md) · [Веб-интерфейс](user-guide.md)

## Подготовка компьютера

Нужны Windows, Python, Git для клонирования проекта и хотя бы одна установленная
копия MetaTrader 5. Текущая реализация проверена на Python 3.14; пакеты перечислены
в `requirements.txt`, зависимость от Python API `MetaTrader5` отсутствует.

Один раз установите MT5 обычным способом и запустите `terminal64.exe /portable`.
Для работы менеджера все управляемые копии также запускаются в portable-режиме.
Выберите каталог, в который текущий пользователь может записывать файлы.
Приложение и терминалы должны работать от одного пользователя Windows, поскольку
используют его общую папку `MetaQuotes/Terminal/Common/Files`.

## Размещение проекта

Рекомендуемое расположение — `MQL5/Shared Projects/mt5-manager` внутри установки
MT5. Например, при установке в `C:\MT5\MetaTrader5.1` корень проекта будет
`C:\MT5\MetaTrader5.1\MQL5\Shared Projects\mt5-manager`.

Так менеджер может найти EXE, каталог серверов и MetaEditor этой установки, а
скомпилированный сервис попадает в ожидаемую папку `MQL5/Services/Shared Projects`.
Команды клонирования и создания Python-окружения приведены в [README](../README.md).
Все команды запуска выполняются из корня проекта.

Проект можно разместить отдельно, например в `C:\Apps\mt5-manager`. На странице
«Настройки» укажите «Папку установки MT5 для получения файлов» (`mt5_installation`),
например `C:\MT5\MetaTrader5.1`. Либо загрузите оба EXE и `servers.dat` через
интерфейс или подготовьте папку-образец с ними. Компиляция сервиса работает и при
отдельном размещении: используется доступный MetaEditor и исходник текущего проекта.
Готовый EX5 можно загрузить вместо сборки.

## Личная конфигурация

В репозитории есть [config.example.json](../config.example.json) с пустым списком
терминалов. Создайте из него `config.local.json`, как показано в README. Команды
там подставляют путь к `Common/Files` текущего пользователя и создают каталог,
если его ещё нет. Не запускайте пример с буквальным `USERNAME` в пути.

`config.local.json` исключён из Git. Исходный `config.json` менять для первого
запуска не требуется. При старте указывайте личный файл явно:

```powershell
.\.venv\Scripts\python.exe run.py --config-file config.local.json --host 127.0.0.1 --port 8000
```

Данные о базе, папках и существующих экземплярах описаны в
[справочнике конфигурации](configuration.md).

## Файлы для создания терминала

На странице «Настройки» доступна загрузка четырёх файлов:

| Файл | Для чего нужен |
|---|---|
| `terminal64.exe` | Исполняемый файл MT5 |
| `MetaEditor64.exe` | Редактор и компилятор MQL5 |
| `servers.dat` | Сведения о торговых серверах; в образце хранится как `config/servers.dat` |
| `ServiceStateWriter.ex5` | Сервис, который передаёт состояние через SQLite |

Если отдельный файл не загружен, EXE и `config/servers.dat` берутся из указанной
установки MT5; установка с проектом определяется автоматически только для
`MQL5/Shared Projects`. Для сервиса при отсутствии заданного пути и загруженного EX5 вызывается
компиляция из исходника проекта. Если сборка уже не старее MQ5, она используется
повторно. Неудачная компиляция останавливает создание нового экземпляра; можно
собрать сервис вручную в MetaEditor или загрузить готовый EX5.

Для ручной сборки откройте `ServiceStateWriter.mq5` в MetaEditor и нажмите F7.
Для отдельного проекта EX5 создаётся рядом с исходником; в Shared Projects —
в соответствующей подпапке `MQL5/Services`. Можно указать полученный файл в
`service_ex5` или загрузить его через настройки.

Перед подготовкой `servers.dat` найдите нужного брокера в диалоге открытия счёта
локального терминала. Файл-образец должен содержать сведения обо всех торговых
серверах, которые планируется использовать при создании новых экземпляров.
После обновления файла закройте локальный терминал и загрузите его
`config/servers.dat` на сервер менеджера. Установленные экземпляры при загрузке
не изменяются.

## Первый экземпляр

Проверьте `mt5_folder` и исходные файлы в настройках. На главной странице нажмите
«Новый терминал». Можно оставить счёт пустым или указать уже существующие логин,
сервер и пароль. Менеджер не открывает демо- или реальные счета самостоятельно.

Создание завершится только после получения свежего состояния от сервиса, а при
заданных реквизитах — после проверки первого подключения и повторного обычного
запуска. Последовательность и возможные ошибки разобраны в
[руководстве по интерфейсу](user-guide.md).

## Уже установленные экземпляры

Укажите их базовую папку в `mt5_folder` и добавьте имена подпапок в `terminals`
личной конфигурации. Отдельное расположение для экземпляра не задаётся.
В каждом должен быть сервис по пути
`MQL5/Services/Shared Projects/mt5-manager/ServiceStateWriter.ex5` и файл
`config/services.ini` из `static/services.ini`. Значение `InpDatabase` должно
совпадать с именем базы менеджера; формат файла — UTF-16.

После изменения JSON вручную перезапустите менеджер. Способ развёртывания
сервиса сразу по нескольким существующим терминалам и ограничения скрипта
описаны в [руководстве по эксплуатации](maintenance.md).