Docker ru RU

Docker

Начиная с версии 3.0.3.2, ASF также доступен в формате контейнера docker. Наши Docker-пакеты доступны на ghcr.io а также Docker Hub.

Важно отметить, что запуск ASF в Docker-контейнере считается расширенной установкой,что не требуется для подавляющего большинства пользователей и обычно не дает никаких преимуществ по сравнению с установкой без контейнеров. If you're considering Docker as a solution for running ASF as a service, for example making it start automatically with your OS, then you should consider reading management section instead and set up a proper systemd service which will be almost always a better idea than running ASF in a Docker container.

Running ASF in Docker container usually involves several new problems and issues that you'll have to face and resolve yourself. This is why we strongly recommend you to avoid it unless you already have Docker knowledge and don't need help understanding its internals, about which we won't elaborate here on ASF wiki. This section is mostly for valid use cases of very complex setups, for example in regards to advanced networking or security beyond standard sandboxing that ASF comes with in systemd service (which already ensures superior process isolation through very advanced security mechanics). For those handful amount of people, here we explain better ASF concepts in regards to its Docker compatibility, and only that, you're assumed to have adequate Docker knowledge yourself if you decide to use it together with ASF.

This tag always points to the ASF built from latest commit in main branch, which works the same as grabbing latest artifact directly from our CI pipeline. Обычно вам стоит избегать использования этого тега, поскольку на этом уровне в программе наибольшая вероятность наличия ошибок, и эта сборка предназначена для разработчиков и продвинутых пользователей принимающих участие в разработке. 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, включая предварительные. Compared to main tag, this image is being updated each time a new GitHub tag is pushed. Предназначен для продвинутых пользователей, которые предпочитают самые свежие версии программного обеспечения, находящиеся на грани того, что можно считать стабильным. Мы рекомендуем это если вы по какой-то причине не хотите использовать тег latest. In practice, it works the same as rolling tag pointing to the most recent A.B.C.D release at the time of pulling. Пожалуйста, обратите внимание, что использование этого тега аналогично использованию предварительных версий.

`latest`

This tag in comparison with others, is the only one that includes ASF auto-updates feature and points to the latest stable ASF version. Цель этого тега - предоставить разумный контейнер Docker по умолчанию, способный запускать само-обновляемую сборку ASF под конкретную ОС. Поэтому этот образ не должен обновляться как можно чаще, поскольку используемая версия ASF способна при необходимости обновиться самостоятельно. Разумеется, UpdatePeriod можно спокойно выключить (поставить равным 0), но в этом случае вам наверное лучше использовать фиксированный билд A.B.C.D. Аналогично, вы можете изменить значение по умолчанию в UpdateChannel чтобы сделать авто-обновляемым тег released.

Due to the fact that the latest image comes with capability of auto-updates, it includes bare OS with OS-specific linux ASF version, contrary to all other tags that include OS with .NET runtime and generic ASF version. Это связано с тем, что более новая (обновленная) версия 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 в качестве услуги. People that are rebuilding their images quite often and would instead prefer full control with ASF version tied to given release are welcome to use released tag. Если же вы вместо этого хотите конкретную и фиксированную версию 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 docker image is currently built on linux platform targetting 3 architectures - x64, arm and arm64. Вы можете прочитать больше об этом в разделе Совместимость.

Since ASF version V5.0.2.2, our tags are using multi-platform manifest, which means that Docker installed on your machine will automatically select the proper image for your platform when pulling the image. If by any chance you'd like to pull a specific platform image which doesn't match the one you're currently running, you can do that through --platform switch in appropriate docker commands, such as docker run. See docker documentation on image manifest for more info.

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

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

Hello ASF!

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

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

docker run создаёт новый контейнер docker с ASF и запускает его на переднем плане (-it). --pull always ensures that up-to-date image will be pulled first, and --rm ensures that our container will be purged once stopped, since we're just testing if everything works fine for now.

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

Если вы внимательно посмотрите на команды выше, вы заметите что мы не задали тег, и поэтому по умолчанию автоматически используется тег latest. If you want to use other tag than latest, for example released, then you should declare it explicitly:

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 container by default is initialized with default root user, which allows it to handle the internal permissions stuff and then eventually switch to asf (UID 1000) user for the remaining part of the main process. While this should be satisfying for the vast majority of users, it does affect the shared volume as newly-generated files will be normally owned by asf user, which may not be desired situation if you'd like some other user for your shared volume.

Docker позволяет вам указать флаг --user команде docker run, что задаст пользователя по умолчанию, под которым будет запускаться ASF. Вы можете посмотреть ваши uid и gid например с помощью команды id, и затем передать их в команде. Например, если нужный вам пользователь имеет uid и gid равные 1001:

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

Remember that by default /app directory used by ASF is still owned by asf. Если вы запустите ASF от произвольного пользователя, то ваш процесс ASF не будет иметь прав на запись в свои собственные файлы. Этот доступ не является обязательным для работы, но он необходим например для автоматического обновления. In order to fix this, it's enough to change ownership of all ASF files from default asf to your new custom user.

docker exec -u root asf chown -hR 1001:1001 /app

Это нужно сделать только один раз после создания вашего контейнера командой docker run, и только если вы решите запускать процесс ASF под своим пользователем. Также не забывайте заменить аргумент 1001:1001 в командах выше на uid и gid которые вы реально хотите использовать для запуска ASF.

Volume with SELinux

If you're using SELinux in enforced state on your OS, which is the default for example on RHEL-based distros, then you should mount the volume appending :Z option, which will set correct SELinux context for it.

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

This will allow ASF to create files targetting the volume while inside docker container.

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

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
# And so on, all ASF containers are now synchronized with each other

Мы рекомендуем привязывать папку /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 и передавать нужные аргументы командной строки самостоятельно.

Unless you want to provide custom encryption key or other advanced options, usually you don't need to include any special environment variables, as our docker containers are already configured to run with a sane expected default options of --no-restart --process-required --system-required, so those flags do not need to be specified explicitly in ASF_ARGS.

IPC

Assuming you didn't change the default value for IPC global configuration property, it's already enabled. However, you must do two additional things for IPC to work in Docker container. Firstly, you must use IPCPassword or modify default KnownNetworks in custom IPC.config to allow you to connect from the outside without using one. Unless you really know what you're doing, just use IPCPassword. Secondly, you have to modify default listening address of localhost, as docker can't route outside traffic to loopback interface. Пример настройки, при которой запросы будут ожидаться со всех интерфейсов - 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 --name asf --pull always justarchi/archisteamfarm

This assumes that you'll use a single ASF container, with all ASF config files in /home/archi/ASF/config. Вам нужно изменить путь к конфигурационным файлам на соответствующий вашей машине. Эта конфигурация также готова к использованию IPC если вы решите включить в вашу папку конфигурации файл IPC.config со следующим содержимым:

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

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

Когда ваш контейнер docker с ASF уже готов, вам не нужно каждый раз использовать команду docker run. Вы можете легко запускать/останавливать контейнер docker с ASF командами docker stop asf и docker start asf. Keep in mind that if you're not using latest tag then using up-to-date ASF will still require from you to docker stop, docker rm and docker run again. Это связано с тем, что вам нужно пересобирать ваш контейнер из свежего образа 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).

Как сказано выше, 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.