Docker pt BR

Docker

A partir da versão 3.0.3.2, o ASF também está disponível como um container docker. Executar o ASF em um contêiner docker normalmente não tem vantagens para usuários casuais, mas pode ser uma excelente forma de usar o ASF em servidores, garantindo que a ASF esteja sendo executado em um ambiente restrito, separado de todos os outros aplicativos. Nossos pacotes docker estão disponíveis atualmente no ghcr.io e no Docker Hub.

Marcadores

O ASF está disponível 4 tipos marcadores principais:

`main`

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. Normalmente você deve evitar essa versão, já que ela contém o nível mais elevado de software com erros, dedicado para desenvolvedores e usuários avançados para fins de desenvolvimento. The image is being updated with each commit in the main GitHub branch, therefore you can expect very often updates (and stuff being broken). Esse marcador está aqui para anotarmos o estado atual do projeto ASF, que não tem necessariamente garantia de ser estável ou testado, como salientado no nosso ciclo de lançamento. Esse marcador não deve ser usado em nenhum ambiente de produção.

`released`

Muito semelhante ao anterior, esse marcador sempre aponta para a versão mais recente do ASF, incluindo pré-lançamentos. Comparado ao marcador main, essa imagem é atualizada toda vez que um novo marcador é criado no GitHub. Dedicado a usuários avançados que gostam de viver no limite do que pode ser considerado estável e mais novo ao mesmo tempo. Esse é o marcador que recomendamos se você não quer usar o latest. Observe que usar esse marcador é igual a usar o pre-lançamentos.

`latest`

Esta tag é a única que inclui o recurso de atualizações automáticas e aponta para a última versão estável do ASF. O objetivo dessa tag é fornecer um contêiner Docker padrão que é capaz de executar a atualização automática do ASF na versão específica de OS. Por conta disso, a imagem não precisa ser atualizada tão frequentemente, já que a versão inclusa do ASF será capaz de se atualizar automaticamente sempre que preciso. Claro, UpdatePeriod pode ser desabilitado sem problemas (definido para 0), mas neste caso é melhor usar a versão congelada A.B.C.D. Da mesma forma, você pode modificar o UpdateChannel padrão para o canal de atualização automática 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 Core runtime and generic ASF version. Isso acontece porque a versão mais recente do ASF (atualizada) também pode exigir um tempo de execução mais recente do que aquele com que a imagem possivelmente pode ter sido compilada, o que exigiria que a imagem fosse reconstruída do zero, anulando o tipo de uso planejado.

`A.B.C.D`

Em comparação com os marcadores acima, esse marcador é completamente congelado, o que significa que a imagem não será atualizada uma vez que foi lançada. Ele funciona de forma semelhante as nossas versões do GitHub que nunca mais foram tocadas após o lançamento, o que te garante um ambiente estável e congelado. Normalmente você deverá usar esse marcador quando você quer usar uma versão específica do ASF (mais antiga que a latest) e você não quer usar nenhum tipo de atualização automática (por exemplo, as oferecidas no marcador latest).

Qual o melhor marcador para mim?

Isso depende do que você procura. Para a maioria dos usuários o marcador latest deve ser o melhor, uma vez que ele oferece exatamente a mesma coisa que o ASF da área de trabalho oferece, com a diferença do serviço especial do contêiner 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. Se, ao invés disso, você preferir usar uma versão congelada específica do ASF que nunca vai mudar sem a sua intenção, as versões A.B.C.D. estão disponíveis para você como marcas as quais você sempre pode voltar.

We generally discourage trying main builds, as those are here for us to mark current state of ASF project. Nada garante que tal versão vai funcionar corretamente, mas é claro, você é mais que bem vindo para fazer um teste se estiver interessado no desenvolvimento do ASF.

Arquiteturas

A imagem docker do ASF é compilada atualmente no linux com 3 arquiteturas: x64, arm e arm64. Você pode ler mais sobre elas em estatísticas.

Desde a versão V5.0.2.2 do ASF, nossas tags tem usado um manifesto multi-plataforma, o que significa que o Docker instalado na sua máquina irá selecionar automaticamente a imagem adequada da sua plataforma ao puxar a imagem. Se por acaso você quiser baixar a imagem de alguma plataforma específica que não corresponde à que você está executando atualmente, você pode usar o switch --platform nos comandos docker apropriados, tal como docker run. Veja a documentação docker em image manifest para mais informações.

Uso

Para uma referência completa você deve usar a documentação docker oficial, nós cobriremos apenas o uso básico nesse guia, você é mais que bem vindo a pesquisar mais a fundo.

Olá ASF!

Primeiro devemos verificar se nosso docker está funcionando corretamente, isso funcionará como uma versão do ASF do "olá mundo":

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

docker run cria um novo contêiner docker do ASF para você e o executa em primeiro plano (-it). --pull always garante que a imagem atualizada seja tirada primeiro, e --rm garante que nosso contêiner seja excluído assim que parado, já que por enquanto estamos apenas testando se está tudo certo.

Se tudo correu bem, após receber todas as camadas e iniciar o contêiner, você deverá notar que o ASF foi iniciado e nos informou que não há bots definidos, o que é bom; nós acabamos de verificar que o ASF funcionou corretamente no docker. Aperte CTRL+P e então CTRL+Q para sair do contêiner docker em primeiro plano, então pare o contêiner ASF com o comando docker stop asf.

Se você olhar para o comando você vai notar que nós não declaramos nenhum marcador, que automaticamente usa o padrão latest. Se você quiser usar uma tag que não seja a latest, a tag released por exemplo, então você deve declarar explicitamente:

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

Usando um volume

Se você estiver usando o ASF em um contêiner docker, então obviamente você precisa configurar o programa. Você pode fazer isso de diversas formas diferentes, mas a forma recomendada é criar a pasta config do ASF no computador local, então carregá-la como um volume compartilhado no contêiner docker do ASF.

Por exemplo, assumiremos que sua pasta config do ASF está no diretório /home/archi/ASF/config. Essa pasta contém o arquivo principal ASF.json bem como os bots que queremos executar. Agora tudo o que temos que fazer é anexar essa pasta como um volume compartilhado no nosso contêiner docker, onde o ASF espera sua pasta config (/app/config).

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

É isso, agora nosso contêiner docker do ASF usará a pasta compartilhada com nosso computador local em modo de leitura e gravação, isso é tudo o que você precisa para configurar o ASF. Da mesma forma, você pode montar outros volumes que você gostaria de compartilhar com o ASF, tais como /app/logs ou /app/plugins.

Claro, essa é apenas uma forma específica de alcançar o resultado que queremos, nada te impede de, por exemplo, criar seu próprio Dockerfile que copie seus arquivos de configuração para a pasta /app/config dentro do contêiner docker do ASF. Estamos cobrindo apenas o uso básico nesse guia.

Permissões de volume

O ASF roda sob o usuário root dentro de um contêiner por padrão. Isso não é um problema quanto a segurança, uma vez que já estamos dentro de um contêiner Docker, mas isso afeta o volume compartilhado uma vez que novos arquivos gerados normalmente pertencerão ao root, o que pode não ser desejado quando se usa um volume compartilhado.

O Docker te permite adicionar uma flag --user no comando docker run para definir sob qual usuário padrão o ASF deve ser executado. Você pode verificar, por exemplo, seu uid e gid com o comando id e, em seguida, passar ao resto do comando. Por exemplo, se seu usuário alvo tem o valor 1000 de uid e gid:

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

Lembre-se que por padrão a pasta /app usada pelo ASF ainda pertence ao root. Se você executar ASF sob um usuário personalizado, então seu processo ASF não terá acesso de gravação aos seus próprios arquivos. Este acesso não é obrigatório para a operação, mas é crucial, por exemplo, para o recurso de atualizações automáticas. Para corrigir esse problema, basta alterar a propriedade de todos os arquivos ASF do padrão root para seu novo usuário personalizado.

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

Isso só tem que ser feito uma vez depois que você criou seu contêiner com docker run, e somente se você decidiu usar um usuário personalizada para o processo do ASF. Também não se esqueça de alterar o argumento 1000:1000 em ambos os comandos acima para o uid e gid sob o qual você deseja executar o ASF.

Sincronização de múltiplas instâncias

O ASF inclui suporte para sincronização de múltiplas instâncias, como indicado na seção de compatibilidade. Ao executar o ASF no contêiner docker, você pode opcionalmente "ligá-lo" ao processo caso você esteja executando vários contêineres com o ASF e você gostaria que eles sincronizassem um com o outro.

Por padrão, cada ASF rodando dentro de um contêiner docker é independente, o que significa que não há sincronização. Para ativar a sincronização entre eles você deve vincular o caminho /tmp/ASF em cada contêiner ASF que você deseja sincronizar, para um caminho compartilhado no seu host docker, em modo de leitura-escrita. Isto é feito exatamente da mesma forma que vincular um volume, como foi descrito acima, apenas com caminhos diferentes:

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
# E assim por diante, todos os conteiner ASF estarão sincronizados agora

Recomendamos vincular a pasta /tmp/ASF do ASF também à pasta /tmp temporária no seu computador, mas claro que você é pode escolher qualquer outra pasta a seu gosto. Cada contêiner do ASF que se espera ser sincronizado deve ter sua pasta /tmp/ASF compartilhada com outros contêineres que participam do mesmo processo de sincronização.

Como você provavelmente percebeu no exemplo acima, também é possível criar dois ou mais "grupos de sincronização", vinculando diferentes caminhos do host docker na pasta /tmp/ASF do ASF.

Montar a pasta /tmp/ASF é completamente opcional e na verdade não é recomendado, a menos que você queira sincronizar explicitamente dois ou mais contêineres do ASF. Não recomendamos montar a pasta /tmp/ASF para uso de apenas um contêiner, já que isso não traz absolutamente nenhum benefício se você espera executar apenas um contêiner do ASF, e na verdade poderia causar problemas que, de outra forma, poderiam ser evitados.

Argumentos da linha de comando

O ASF te permite passar argumentos de linha de comando no contêiner docker através de variáveis de ambiente. Você deve usar variáveis de ambiente específicas para os switches suportados, e ASF_ARGS para o resto. Isso pode ser feito com o switch -e adicionado ao docker run, por exemplo:

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

Esse comando passará seu argumento --cryptkey para o processo do ASF sendo executado dentro do contêiner docker, assim como outros argumentos. Claro, se você for um usuário avançado então você também pode mudar o ENTRYPOINT ou adicionar CMD e passar seus argumentos personalizados você mêsmo.

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. Um exemplo de configuração que irá escutar em todas as interfaces é http://*:1242. Claro, você também pode usar vinculos mais restritivos, tais como apenas rede local (LAN) ou VPN, mas tem que ser uma rota acessível de fora; localhost não funciona, já que a rota está inteiramente dentro do computador de convidado.

Para obter o resultado descrito acima você deve usar uma configuração personalizada de IPC, como o exemplo abaixo:

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

Depois de configurarmos o IPC em uma interface sem loopback, precisamos indicar ao docker para se conectar a porta 1242/tcp do ASF com o argumento -P ou -p.

Por exemplo, este comando vai expor a interface do IPC do ASF para o computador host (somente):

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

Se você definiu tudo corretamente, o comando docker run acima fará com que a interface IPC funcione em seu computador host, no caminho padrão localhost:1242 que agora é redirecionada para seu computador convidado. Também é bom notar que nós não expomos esta rota além disso, então a conexão só pode ser feita dentro do host docker, e, portanto, o mantém seguro. Claro, você pode expor mais a rota e garantir medidas de segurança adequadas se você souber o que está fazendo.

Exemplo completo

Combinando todo conhecimento acima, um exemplo de uma configuração completa ficaria assim:

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

Isso pressupõe que você usará um único contêiner do ASF, com todos os arquivos de configuração em /home/archi/asf. Você deve modificar o caminho de configuração para aquele que corresponde à sua máquina. Essa configuração também está pronta para o uso opcional do IPC se você decidiu incluir o arquivo IPC.config na sua pasta config com o conteúdo abaixo:

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

Dicas profissionais

Quando você já tem o contêiner docker do ASF pronto, você não precisa usar o comando docker run toda vez. Você pode parar/iniciar o contêiner docker do ASF facilmente com docker stop asf e docker start asf. Tenha em mente que se você não estiver usando o marcador latest então você precisará usar os comandos docker stop, docker rm e docker run novamente para atualizar o ASF. Isso porque você deve recompilar seu contêiner à partir de uma imagem nova do ASF toda vez que você quiser usar a versão do ASF inclusa naquela imagem. 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 Core dependencies and the underlying OS).

Como dito acima, em qualquer outro marcador que não seja o latest, o ASF não vai se atualizar automaticamente, o que significa que você é o responsável por usar uma verão atualizada do repositório justarchi/archisteamfarm. Isso traz muitas vantagens já que normalmente o aplicativo não precisa mudar seu código durante a operação, mas nós entendemos a conveniência de não precisar se preocupar com a versão do ASF em seu contêiner docker. Se você se importa com boas práticas e o uso correto do contêiner docker, sugerimos o marcador released ao invés de latest, mas se você não quer se preocupar com isso e só quer fazer o ASF tanto funcionar quanto se atualizar automaticamente, então latest serve.

Você normalmente deve rodar o ASF no contêiner docker com a configuração global Headless: true. Isso indicará explicitamente ao ASF que você não poderá inserir os dados ausentes e que ele não deverá solicitá-los. Claro, para a configuração inicial você deve deixar essa opção como false então você poderá configurar tudo facilmente, mas no longo prazo você normalmente não estará ligado diretamente ao console do ASF, portanto faz sentido informar o ASF sobre isso e usar o comando input caso seja necessário. Dessa forma o ASF não vai esperar infinitamente por um comando do usuário que não será inserido (e gastar recursos enquanto isso). Isso também permitirá que o ASF rode em modo não-interativo dentro do contêiner, o que é crucial, por exemplo, no que diz respeito a sinais de encaminhamento, tornando possível que o ASF feche com o comando docker stop asf.