Docker ru RU

Docker

ASF доступен как контейнер докер. Наши пакеты докеров в настоящее время доступны на ghcr.io и Docker Hub.

Важно отметить, что запуск ASF в Docker-контейнере считается расширенной установкой,что не требуется для подавляющего большинства пользователей и обычно не дает никаких преимуществ по сравнению с установкой без контейнеров. Если вы рассматриваете Docker в качестве решения для запуска ASF в качестве службы, например заставляя его автоматически запускаться с вашей ОС, то вы должны подумать над чтением раздела управления и установкой соответствующего сервиса, который будет почти всегда лучшей идеей, чем запуск ASF в контейнере Docker.

Запуск ASF в контейнере Docker обычно включает в себя новых проблем и проблем, с которыми вам придется столкнуться и решить. Именно поэтому мы сильно рекомендуем вам избегать этого, если только вы не обладаете знаниями о Docker и не нуждаетесь в помощи в понимании его внутренностей, о которых мы не будем подробно рассказывать здесь, на ASF вики. Этот раздел в основном предназначен для правильных вариантов использования очень сложных настроек, Например, в отношении развитой сети или безопасности помимо стандартной системы "песочница", которую ASF поставляет в службе systemd (которая уже обеспечивает превосходную изоляцию процесса через очень продвинутые механизмы безопасности). Для этих небольшого количества людей, здесь мы объясняем лучшие понятия ASF в отношении его Docker совместимость, и только то, что вы предполагаете, что имеете адекватные знания Docker, если вы решите использовать его вместе с ASF.

---

Теги

В ASF доступные 4 основных типа тегов:

main

Этот тег всегда указывает на ASF, созданный из последнего коммита в основной ветке , который работает так же, как и захват последнего артефакта непосредственно из трубопровода CI. Обычно вам стоит избегать использования этого тега, поскольку на этом уровне в программе наибольшая вероятность наличия ошибок, и эта сборка предназначена для разработчиков и продвинутых пользователей принимающих участие в разработке. The image is being updated with each commit in the main GitHub branch, therefore you can expect very often updates (and stuff being broken). Эта сборка отображает текущее состояние проекта ASF, и не гарантируется что она стабильна и протестирована, как и указано в описании цикла выпуска. Этот тег не следует использовать в среде реального применения.

released

По аналогии с тегом выше, этот тег всегда соответствует последней версии ASF, включая предварительные. По сравнению с основным тегом это изображение обновляется каждый раз при нажатии нового тега GitHub. Предназначен для продвинутых пользователей, которые предпочитают самые свежие версии программного обеспечения, находящиеся на грани того, что можно считать стабильным. Мы рекомендуем это если вы по какой-то причине не хотите использовать тег latest. На практике он работает так же, как и ротк-тег, указывающий на последний релиз A.B.C.D во время вытягивания. Пожалуйста, обратите внимание, что использование этого тега аналогично использованию предварительных версий.

latest

Этот тег по сравнению с другими, это единственная функция, которая включает в себя функцию автоматического обновления ASF и указывает на последнюю версию стабильной ASF. Цель этого тега - предоставить разумный контейнер Docker по умолчанию, способный запускать само-обновляемую сборку ASF под конкретную ОС. Поэтому этот образ не должен обновляться как можно чаще, поскольку используемая версия ASF способна при необходимости обновиться самостоятельно. Разумеется, UpdatePeriod можно спокойно выключить (поставить равным 0), но в этом случае вам наверное лучше использовать фиксированный билд A.B.C.D. Аналогично, вы можете изменить значение по умолчанию в UpdateChannel чтобы сделать авто-обновляемым тег released.

Из-за того, что последнее изображение `` имеет возможность автоматического обновления, он включает в себя bare OS с версией linux ASF, в отличие от всех других тегов, которые включают ОС с . ET runtime и `generic` ASF версии. Это связано с тем, что более новая (обновленная) версия ASF может потребовать более новую среду выполнения, чем та, с которой собран образ, что в противном случае потребовало бы пересборку заново, сводя на нет планируемый вариант использования.

A.B.C.D

В сравнении с тегами выше, этот тег полностью зафиксирован, это означает что образ не будет обновляться после публикации. Это работает аналогично сборкам на GitHub, которые никогда не меняются после выпуска, что гарантирует стабильную и неизменную среду. Typically you should use this tag when you want to use some specific ASF release and you don't want to use any kind of auto-updates (e.g. those offered in latest tag).

---

Какой тег лучше для меня?

Это зависит от того, что вам нужно. Для большинства пользователей наилучшим будет тег latest, поскольку он предоставляет в точности то же, что и ASF для домашних ПК, но в особом контейнере Docker в качестве услуги. Люди, которые довольно часто перестраивают свои образы и предпочитают полностью управлять версией ASF, привязанной к данному релизу, могут использовать тег выпущенный. Если же вы вместо этого хотите конкретную и фиксированную версию ASF, которая никогда не изменится без вашего явного желания, то для вас доступны сборки A.B.C.D на различных этапах развития, к которым вы всегда можете вернуться.

We generally discourage trying main builds, as those are here for us to mark current state of ASF project. Нет никаких гарантий что это состояние будет правильно работать, но конечно же вы можете попробовать его использовать если интересуетесь разработкой ASF.

---

Архитектуры

Образ ASF построен на платформе linux с запуском 3 архитектур - x64, рука и arm64. Вы можете прочитать больше об этом в разделе Совместимость.

Наши теги используют мультиплатформенный манифест, , это означает, что Docker установлен на вашей машине автоматически выберет подходящий образ для вашей платформы при получении изображения. Если вы хотите получить конкретный образ платформы, который не соответствует тому, который вы сейчас запущен, вы можете сделать это через --platform переключить соответствующие команды докера, такие как docker run. Смотрите документацию docker на image manifest для получения дополнительной информации.

---

Использование

Полную справку вы можете найти в официальной документации docker, а мы в этом руководстве рассмотрим только базовое использование, но вы можете узнать больше самостоятельно.

Hello ASF!

Для начала нам надо проверить что наш docker работает правильно, и этот пример послужит для ASF своего рода "hello world":

docker run -it --name asf --pull always --rm justarchi/archisteamfarm

docker run создаёт новый контейнер docker с ASF и запускает его на переднем плане (-it). --pull always гарантирует, что сначала будет выгружено обновленное изображение. и --rm гарантирует, что наш контейнер после остановки будет очищен, так как мы просто тестируем, если все работает нормально.

Если всё завершилось успешно, после получения всех слоев и запуска контейнера вы должны увидеть что ASF успешно запустился и сообщил вам что в нём не задано ботов, это хорошо - мы проверили что ASF корректно работает в docker. Нажмите CTRL+C для завершения процесса ASF и, следовательно, и контейнера.

Если вы внимательно посмотрите на команды выше, вы заметите что мы не задали тег, и поэтому по умолчанию автоматически используется тег latest. Если вы хотите использовать тег, отличный от latest, например latest-arm, тогда его нужно задать в явном виде:

docker run -it --name asf --pull always --rm justarchi/archisteamfarm:released

---

Использование тома

Если вы используете ASF в контейнере docker то очевидно что вам нужно сконфигурировать саму программу. Это можно сделать различными методами, но мы рекомендуем создать папку ASF config на локальной машине, и подключить её как общий том к контейнеру docker с ASF.

Например, предположим что ваша папка config для ASF находится по адресу /home/archi/ASF/config. Эта папка содержит ASF.json а также файлы конфигурации для ботов, которых мы хотим запустить. Теперь всё что нам нужно сделать это просто подключить эту папку как общий том к нашему контейнеру docker, там где ASF ожидает найти свою папку конфигурации (/app/config).

docker run -it -v /home/archi/ASF/config:/app/config --name asf --pull always justarchi/archisteamfarm

Вот и всё, теперь ваш контейнер docker с ASF будет использовать общую папку с вашей локальной машины в режиме чтения и записи, а это всё что вам нужно для конфигурирования ASF. Аналогичным образом вы можете смонтировать другие тома, которые вы хотите поделиться с ASF, такие как /app/logs или /app/plugins.

Разумеется, это только один из возможных способов получить желаемое, никто не мешает вам, к примеру, создать свой собственный Dockerfile который будет копировать файлы конфигурации в папку /app/config в контейнере docker с ASF. В этой инструкции мы описываем только основы использования.

Разрешения для тома

Контейнер ASF по умолчанию инициализирован с пользователем корня , , который позволяет ему обрабатывать внутренние права и затем переключиться на пользователя asf (UID 1000) для оставшейся части основного процесса. Хотя это должно быть удовлетворено подавляющим большинством пользователей, это влияет на общий том, так как новые сгенерированные файлы обычно принадлежат пользователю asf которая может быть не желаемой ситуацией, если вам понравится другой пользователь для вашего общего тома.

Существует два способа изменения пользовательского ASF запущен. Первый, рекомендуется объявить переменную окружения ASF_USER с целевым UID, под которым вы хотите запустить. Во-вторых, альтернативой является передача --user флага, который напрямую поддерживается docker.

Вы можете проверить ваш uid например с командой id -u , а затем объявить его, как указано выше. Например, если у вашего целевого пользователя Uid 1001:

docker run -it -e ASF_USER=1001 -v /home/archi/ASF/config:/app/config --name asf --pull always justarchi/archisteamfarm

# Или если вы понимаете ограничения ниже
запустить -it -u 1001 -v /home/archi/ASF/config:/app/config --name asf --pull всегда justarchi/archisteamfarm

Разница между флагом ASF_USER и --user является тонкой, но важной. ASF_USER — пользовательский механизм, поддерживаемый ASF, в этом контейнере докеров сценариев все еще запускается как корень, и затем скрипт запуска ASF запускает основной бинарный файл под ASF_USER. При использовании флага --user вы запускаете весь процесс, включая сценарий запуска ASF как заданный пользователь. Первый параметр позволяет ASF запускать скрипт автоматически обрабатывать права доступа и другие вещи для вас, решая некоторые общие проблемы, которые вы вызвали, Например, это гарантирует, что ваши директории /app и /asf фактически принадлежат ASF_USER. Во втором случае, поскольку мы не запускаем как root, мы не можем это сделать, и вы должны обработать все это самостоятельно.

Если вы решили использовать флаг --user , вам нужно изменить владельца всех файлов ASF по умолчанию asf на нового пользовательского пользователя. Вы можете сделать это, выполнив команду ниже:

# Выполнять только если вы не используете ASF_USER
docker exec -u root asf chown -hR 1001 /app /asf

Это должно быть сделано только один раз после создания контейнера с помощью докера, запускаемого, и только в том случае, если вы решили использовать пользовательский пользователь через флаг --user docker. Также не забудьте изменить аргумент 1001 в команде выше на UID который вы действительно хотите запустить под ASF.

Раздел с SELinux

Если вы используете SELinux в режиме принудительного применения (enforced) в вашей операционной системе, что по умолчанию происходит, например, в дистрибутивах на основе RHEL, то вам следует монтировать том с опцией :Z, которая установит корректный контекст SELinux для него.

docker run -it -v /home/archi/ASF/config:/app/config:Z --name asf --pull always justarchi/archisteamfarm

Это позволит ASF создавать файлы, нацеленные на данный том, будучи внутри контейнера docker.

---

Синхронизация нескольких экземпляров

ASF включает поддержку синхронизации нескольких экземпляров, как указано в разделе управления. Если вы запускаете ASF в контейнере docker, у вас также есть возможность "включиться" в этот процесс, в случае если у вас несколько контейнеров с ASF и вам нужно синхронизировать их между собой.

По умолчанию каждый ASF, запущенный внутри контейнера docker, автономен, а значит никакая синхронизация не происходит. Чтобы включить синхронизацию между ними, вы должны привязать путь /tmp/ASF в каждом контейнере ASF, который вы хотите синхронизировать, к одному общему пути хост-машины, в режиме чтения-записи. Это делается точно так же, как привязка томов, описанная выше, только с другими путями:

mkdir -p /tmp/ASF-g1
docker run -v /tmp/ASF-g1:/tmp/ASF -v /home/archi/ASF/config:/app/config --name asf1 --pull always justarchi/archisteamfarm
docker run -v /tmp/ASF-g1:/tmp/ASF -v /home/john/ASF/config:/app/config --name asf2 --pull always justarchi/archisteamfarm
# И так далее, все контейнеры ASF теперь синхронизированы друг с другом.

Мы рекомендуем привязывать папку /tmp/ASF вашего ASF тоже к временной папке /tmp на вашей машине, но конечно же вы вольны выбрать любую другую, удовлетворяющую вашим потребностям. Каждый контейнер ASF, который вы хотите синхронизировать, должен делить общую папку /tmp/ASF с другими контейнерами, также участвующими в процессе синхронизации.

Как вы наверное догадались из примера выше, можно также создать две "группы синхронизации", привязав разные пути на хост-машине docker в папке /tmp/ASF в ASF.

Привязка /tmp/ASF совершенно необязательна и даже не рекомендуется, за исключением случая когда вы точно хотите синхронизировать два или более контейнера ASF. Мы не рекомендуем привязку /tmp/ASF для использования одного контейнера, поскольку это не несёт совершенно никакой пользы если вы планируете запускать только один контейнер ASF, и может даже привести к проблемам, которых можно было избежать.

---

Аргументы командной строки

ASF позволяет передавать аргументы командной строки в контейнер docker используя переменные среды. Вам следует использовать выделенные переменные среды для поддерживаемых аргументов, и переменную ASF_ARGS для всего остального. Это достигается путём добавления к команде docker run параметра -e, например:

docker run -it -e "ASF_CRYPTKEY=MyPassword" -e "ASF_ARGS=--no-config-migrate" --name asf --pull always justarchi/archisteamfarm

Этот пример корректно передаст ваш аргумент --cryptkey процессу ASF, запущенному внутри контейнера docker, а также передаст остальные аргументы. Конечно, если вы продвинутый пользователь, то вы можете также изменить ENTRYPOINT или добавить CMD и передать свои пользовательские аргументы самостоятельно.

Если вы не хотите предоставлять пользовательский ключ шифрования или другие расширенные опции, обычно вам не нужно включать никаких специальных переменных среды, так как наши контейнеры docker уже настроены на запуск с ожидаемыми параметрами по умолчанию --no-restart --system-required, так что эти флаги не должны быть явно указаны в ASF_ARGS.

---

IPC

Если вы не изменили значение по умолчанию для глобального файла конфигурации IPC, то он уже включен. Однако, для работы в Docker контейнере необходимо выполнить еще две вещи. Во-первых, вы должны использовать IPCPassword или изменить значение по умолчанию KnownNetworks в пользовательских IPC.config, чтобы позволить вам подключаться снаружи без использования его. Если вы не знаете, что вы делаете, просто используйте IPCPassword. Во-вторых, вы должны изменить адрес прослушивания localhost, так как Docker не может маршрутизировать внешний трафик до loopback-интерфейса. Пример настройки, при которой запросы будут ожидаться со всех интерфейсов - http://*:1242. Разумеется, вы можете указать также более строгие настройки, такие как только приём запросов только от внутренней сети, или сети VPN, но это должен быть маршрут, доступный извне - localhost не подходит, поскольку этот маршрут полностью находится внутри гостевой машины.

Чтобы сделать описанное выше, вам нужно использовать пользовательскую конфигурацию IPC, аналогичную приведенной ниже:

{
    "Kestrel": {
        "Endpoints": {
            "HTTP": {
                "Url": "http://*:1242"
            }
        }
    }
}

После того, как мы настроим IPC на использование интерфейса, отличного от loopback, нам нужно сообщить docker что необходимо подключить порт ASF 1242/tcp с помощью аргумента командной строки -P либо -p.

Например, эта команда сделает доступным интерфейс ASF IPC (только) для хост-машины:

docker run -it -p 127.0.0.1:1242:1242 -p [::1]:1242:1242 --name asf --pull always justarchi/archisteamfarm

Если вы всё настроили правильно, команда docker run, приведенная выше сделает возможной работу с интерфейсом IPC на вашей хост-машине, по стандартному адресу localhost:1242, который теперь корректно маршрутизируется на гостевую машину. Приятно отметить, что мы не маршрутизируем этот адрес дальше, поэтому соединение будет работать только с хост-машины docker, а значит останется безопасным. Разумеется, вы можете разрешить маршрутизацию и далее, если вы понимаете что делаете и предпринимаете соответствующие меры безопасности.

---

Полный пример

Объединив знания, полученные выше, мы можем сделать полный пример конфигурации, он будет выглядеть примерно так:

docker run -p 127.0.0.1:1242:1242 -p [:1]:1242:1242 -v /home/archi/ASF/config:/app/config -v /home/archi/ASF/plugins:/app/plugins --name asf --pull always justarchi/archisteamfarm

Предполагается, что вы будете использовать один ASF контейнер со всеми конфигурационными файлами ASF в /home/archi/ASF/config. Вам нужно изменить путь к конфигурационным файлам на соответствующий вашей машине. Также можно предоставить пользовательские плагины для ASF, которые можно поместить в /home/archi/ASF/plugins. Эта конфигурация также готова к использованию IPC если вы решите включить в вашу папку конфигурации файл IPC.config со следующим содержимым:

{
    "Kestrel": {
        "Endpoints": {
            "HTTP": {
                "Url": "http://*:1242"
            }
        }
    }
}

---

Советы профессионалов

Когда ваш контейнер docker с ASF уже готов, вам не нужно каждый раз использовать команду docker run. Вы можете легко запускать/останавливать контейнер docker с ASF командами docker stop asf и docker start asf. Помните, что если вы не пользуетесь тегом latest, то обновление ASF потребует от вас снова выполнить docker stop, docker rm, docker pull и docker run. Это связано с тем, что вам нужно пересобирать ваш контейнер из свежего образа ASF каждый раз когда вы хотите использовать версию ASF, включенную в этот образ. In latest tag, ASF has included capability to auto-update itself, so rebuilding the image is not necessary for using up-to-date ASF (but it's still a good idea to do it from time to time in order to use fresh .NET runtime dependencies and the underlying OS, which might be needed when jumping across major ASF version updates).

Как сказано выше, ASF c тегами отличными от latest не будут обновляться автоматически, а это значит что вы отвечаете за использование последней версии репозитория justarchi/archisteamfarm. Это имеет много преимуществ, потому что обычно приложение не должно изменять свой код во время работы, но мы также понимаем удобство того факта что вам не нужно беспокоиться о версии ASF в контейнере docker. Если вас заботят хорошие практики и правильное использование docker, мы рекомендуем использовать тег released вместо latest, но если вы не хотите заботиться о нём и просто хотите чтобы ASF работало и обновлялось автоматически, тег latest тоже подойдёт.

Обычно вам следует запускать контейнер docker с ASF с глобальной настройкой Headless: true. Это явным образом укажет ASF что вы не сможете ввести недостающие данные и запрашивать их не следует. Разумеется, для начальной настройки вам стоит рассмотреть возможность оставить этот параметр равным false, чтобы вы легко могли всё настроить, но при длительном использовании вы обычно не привязаны к консоли ASF, и поэтому имеет смысл сообщить об этом ASF и использовать при необходимости команду input. Таким образом ASF не придётся бесконечно ждать пользовательского ввода, который никогда не произойдёт (и тратить на это ресурсы). Это также позволит запускать ASF внутри контейнера в не-интерактивном режиме, что может быть чрезвычайно полезно, например, для пересылки сигналов, делая возможным штатное завершение ASF по запросу docker stop asf.