Docker ru RU

Docker

Начиная с версии 3.0.3.2, ASF также доступен в формате контейнера docker. Запуск ASF в контейнере docker обычно не имеет никаких преимуществ для обычных пользователей, он это может оказаться отличным способом использования ASF на серверах, позволяющий запускать ASF в среде, изолированной от других приложения. Our docker packages are currently available on ghcr.io as well as Docker Hub.

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

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

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

Архитектуры

ASF docker image is currently built on linux platform with 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.

Usage

Полную справку вы можете найти в официальной документации 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 по умолчанию запускается под пользователем root внутри контейнера. С точки зрения безопасности это не проблема, поскольку мы уже находимся внутри контейнера Docker, но это влияет на общий том, поскольку созданные в нём файлы будут обычно иметь в качестве владельца root, что может быть нежелательным при использовании общего тома.

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

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

Не забывайте что по умолчанию папка /app, используемая ASF, всё равно принадлежит root. Если вы запустите ASF от произвольного пользователя, то ваш процесс ASF не будет иметь прав на запись в свои собственные файлы. Этот доступ не является обязательным для работы, но он необходим например для автоматического обновления. Чтобы это исправить достаточно сменить владельца всех файлов ASF со значения по умолчанию root на нужного вам пользователя.

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

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

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

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, и может даже привести к проблемам, которых можно было избежать.

Command-line arguments

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

docker run -it -e "ASF_CRYPTKEY=MyPassword" -e "ASF_ARGS=--process-required" --name asf --pull always justarchi/archisteamfarm

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

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

IPC

Assuming you didn't change the default value for IPC global configuration property, it's already enabled, but 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 -it -p 127.0.0.1:1242:1242 -p [::1]:1242:1242 -v /home/archi/asf:/app/config --name asf --pull always justarchi/archisteamfarm

Предполагается, что у вас один контейнер с ASF, и все конфигурационные файлы ASF расположены в /home/archi/asf. Вам нужно изменить путь к конфигурационным файлам на соответствующий вашей машине. Эта конфигурация также готова к использованию 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, включенную в этот образ. Для образов с тегом latest, в ASF включена возможность автоматического обновления, поэтому пересборка образа не нужна для использования последней версии ASF (но делать это время от времени всё равно полезно, чтобы получить свежую среду выполнения .NET Core и используемую ОС).

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