Instalar e gerenciar GroundRunners

Os GroundRunners permitem que os comandos em cadeia interajam com sistemas locais ou fontes de dados remotas não acessíveis de outra forma pela Internet. Eles geralmente são instalados em um servidor dedicado, como aquele que hospeda sua fonte de dados conectada, por um profissional de TI ou alguém familiarizado com as configurações de rede da sua organização.

Antes de configurar um GroundRunner, recomendamos que você consulte a arquitetura de segurança do Chain Builder .

Requisitos

É necessário um sistema operacional compatível e, se o seu GroundRunner acessar recursos compartilhados, como um caminho UNC (Universal Naming Convention) do Windows, também será necessária uma conta de usuário com privilégios suficientes.

Um Java Runtime Environment (JRE) não é instalado com o GroundRunner durante a instalação inicial do GroundRunner.

Após a conclusão da configuração e o GroundRunner estar em execução, ele fará o download automático de um JRE conforme necessário para executar comandos que dependem do Java. Não é necessária nenhuma instalação ou intervenção do administrador, e o JRE recuperado não afetará as instalações de JRE existentes, se elas existirem no host.

Como alternativa, se você tiver requisitos organizacionais que exijam o uso de um JRE específico, a variável de ambiente SHARED_LIBRARY_OVERRIDES poderá ser definida para apontar para a instalação do sistema. Nesse caso, o GroundRunner não fará o download automático do JRE padrão da Workiva e usará a instalação do JRE do sistema fornecida.

Os JREs fornecidos pela Workiva são licenciados sob a GPL v2 e são cobertos pela exceção de caminho de classe.

Observação: Para usar certificados personalizados com o Java instalado, consulte Usando certificados personalizados com o GroundRunners.

Atualmente, os GroundRunners podem ser instalados nas seguintes famílias de sistemas operacionais sem dependências de bibliotecas externas:

Windows e Windows Server
Distribuições Linux e derivadas:
- RedHat, Fedora, AmazonLinux
- Debian/Ubuntu
macOS (somente para testes)

A Workiva se esforça para oferecer suporte a todas as versões modernas das famílias de sistemas operacionais listadas acima. No entanto, não podemos oferecer suporte a nenhum sistema operacional que tenha sido designado como "fim de vida útil" por seu fornecedor. Esses sistemas operacionais mais antigos representam riscos potenciais de segurança e devem ser atualizados para uma versão atual o mais rápido possível. Saber mais sobre nossa política de fim de vida útil.

Observação: O cronograma de suporte de cada sistema operacional é definido pelo fornecedor individual. Por exemplo, o suporte da Microsoft para o Windows 7 encerrou em 14 de janeiro de 2020; o suporte da Workiva para o Windows 7 encerrou na mesma data.

Requisitos de hardware

Embora os GroundRunners precisem de poucos recursos de servidor, recomendamos pelo menos:

512 MB de memória de acesso aleatório (RAM) disponível
100 GB de espaço em disco disponível

Observação: Para ajudar a calcular o espaço em disco necessário, saiba que uma cadeia com cinco comandos, cada um produzindo saídas efêmeras de 10 MB, requer 50 MB para ser concluída.

A configuração de host recomendada inclui uma máquina virtual configurada com:

Dois a quatro processadores

Nota: Os processadores baseados em ARM não são compatíveis com o GroundRunners.
8 GB de memória do sistema
Um dispositivo de armazenamento de unidade de estado sólido (SSD)

Esse servidor deve estar disponível 24 horas por dia, 7 dias por semana, para que você possa se comunicar com o GroundRunner.

Por padrão, os GroundRunners usam uma conta administrativa local sem acesso a recursos remotos, como unidades compartilhadas.

Para acessar um recurso compartilhado, como um caminho UNC do Windows, inicie o GroundRunner em uma conta de usuário com privilégios adequados para o recurso. Se você estiver usando uma conta de usuário que não seja o administrador do sistema local padrão, conceda a ele permissões para gerenciar o diretório de instalação do GroundRunner para ativar as atualizações automáticas.

Requisitos de função

Na plataforma Workiva

Na plataforma Workiva, você precisa de uma função que conceda acesso às configurações do Construtor de cadeias e a habilidade de gerenciar Runners. Há duas:

Proprietário da cadeia: Esta é a função principal necessária. Os usuários com essa função podem acessar a seção "Downloads" no Construtor de cadeias para obter os arquivos de instalação mais recentes do GroundRunner e gerenciar a aba "Runners" para ativar ou monitorar o serviço.
Administrador de segurança de cadeias da organização: Essa função em nível organizacional também tem autoridade para gerenciar conexões e runners em vários espaços de trabalho.

No servidor

Como uma "atualização manual" envolve a interrupção de serviços e a substituição de arquivos executáveis na máquina física ou virtual onde o GroundRunner está instalado, o usuário deve ter privilégios administrativos no servidor host.

Windows: Você deve ter a habilidade de executar o Prompt de Comando como Administrador e acessar o Gerenciador de Serviços do Windows (para parar e reiniciar o serviço do GroundRunner).
Linux/macOS: Você deve ter acesso sudo ou root para mover arquivos para o diretório de instalação e reiniciar o processo em segundo plano.

Baixar o GroundRunner

Para baixar um GroundRunner para instalação ou atualização manual:

Na barra lateral da página inicial da Workiva, clique em Cadeias.
Na barra lateral do Construtor de cadeias (esta é uma nova aba), clique em Conexões.

Como alternativa, você pode clicar no ícone de perfil do usuário no canto superior direito, selecionar Administrador de cadeias e, em seguida, Configurações do espaço de trabalho.
Clique em Downloads na barra de menu superior.
Localize o GroundRunner para o seu sistema operacional e clique em Baixar.
Após o download bem-sucedido para o seu computador, selecione as instruções apropriadas do conjunto abaixo e siga-as para instalar o GroundRunner.

Instalar o GroundRunner

O Microsoft Installer (MSI) requer o .NET 3.5 ou superior.
Se você não puder atender a esse requisito, precisará instalar o GroundRunner usando a interface de linha de comando.

Para instalar o GroundRunner:

Descompacte GroundRunner.zip em uma nova pasta e abra a pasta.
Execute GroundRunner.msi para abrir o assistente de configuração do GroundRunner.
Clique em Próximo.
Revise e aceite os termos do contrato de licença e clique em Próximo.
Para a pasta de destino, insira o caminho onde o GroundRunner será instalado (por exemplo: C:\Program Files\GroundRunner\) e clique em Próximo.
Em Token da empresa da plataforma, insira seu token da empresa.
Em Host de autenticação da plataforma:
- Para APAC, insira h.apac.wdesk.com/s/chains-reaper.
- Para o Canadá, insira h.ca.wdesk.com/s/chains-reaper.
- Para EMEA, insira h.eu.wdesk.com/s/chains-reaper.
- Para os Estados Unidos, América Central e América do Sul, insira h.app.wdesk.com/s/chains-reaper.
Se estiver usando um servidor proxy, insira sua URL e porta em Host do proxy.
(Por exemplo, http://yourproxy:3000.)
Para ignorar o servidor proxy, insira uma lista separada por vírgulas de hosts em Sem host de proxy.
Clique em Próximo, Instalar e Concluir.
Após a instalação, clique com o botão direito no GroundRunner no Gerenciador de Serviços do Windows e selecione Iniciar.

Seu GroundRunner foi instalado e está pronto para ativação.

Para instalar via interface de linha de comando, você deve baixar a instalação do GroundRunner para seu próprio diretório dentro dos arquivos de programa (por exemplo, c:\Program Files (x86)\wdata). Em seguida, você pode descompactar o arquivo de instalação e extraí-lo para a raiz desse diretório.

Você então pode instalar o GroundRunner:

Na janela de comando do Windows, insira
```
c:\Program Files (x86)\wdata\installer.exe install
```
e aceite todos os padrões.
- Selecione "windows" para o sistema de inicialização.
  
  Você precisa especificar que o GroundRunner deve operar como um serviço Windows para que seja compatível com atualizações automáticas. Os GroundRunners devem ser executados apenas como um serviço, exceto para fins de teste.
- Para o caminho, crie uma pasta Files dentro do novo diretório
  (por exemplo, C:\Program Files (x86)\Wdata\Files).
- Para o nome do host de autorização (AUTH_HOST):
  - Para APAC, insira h.apac.wdesk.com/s/chains-reaper.
  - Para o Canadá, insira h.ca.wdesk.com/s/chains-reaper.
  - Para EMEA, insira h.eu.wdesk.com/s/chains-reaper.
  - Para os Estados Unidos, América Central e América do Sul, insira h.app.wdesk.com/s/chains-reaper.
- Insira seu token da empresa.
Exclua todos os arquivos do diretório, exceto o diretório executável do GroundRunner.
Selecione se você deseja executar o GroundRunner como um serviço ou como um processo em primeiro plano.
- Se estiver executando como um serviço, siga um dos procedimentos abaixo:
  - Na caixa de diálogo de comando, insira sc start GroundRunner.
  - No Gerenciador de Serviços do Windows, inicie o serviço GroundRunner.
- Se estiver executando como um processo em primeiro plano, na caixa de diálogo de comando, insira:
```
cd c:\Program Files (x86)\wdata GroundRunner.exe
```

Seu GroundRunner está instalado e pronto para ativação.

Etapa 1. Instalar o GroundRunner

Baixe o arquivo de instalação do GroundRunner para seu próprio diretório,
por exemplo: /home/user_name/wdata/.

Observação: "/home/user_name/wdata" é fornecido como exemplo. Siga a política da sua organização para locais de instalação de serviços.
Em uma caixa de diálogo de comando, descompacte o arquivo de instalação usando:
```
unzip GroundRunner.zip
```
Insira os detalhes do GroundRunner.
1. Insira ./installer install
2. Para o nome do host de autorização (AUTH_HOST):
  - Para APAC, insira h.apac.wdesk.com/s/chains-reaper.
  - Para o Canadá, insira h.ca.wdesk.com/s/chains-reaper.
  - Para EMEA, insira h.eu.wdesk.com/s/chains-reaper.
  - Para os Estados Unidos, América Central e América do Sul, insira h.app.wdesk.com/s/chains-reaper.
3. Insira seu token da empresa.
Exclua todos os arquivos do diretório, exceto a pasta criada durante o processo de instalação.

Etapa 2. Configurar seu GroundRunner como um serviço systemd (Linux)

Para garantir que as atualizações automáticas do GroundRunner funcionem e para uma boa higiene do GroundRunner, ele precisa ser instalado como um serviço systemd ativado e reiniciável. Consulte a documentação do seu sistema operacional e a política da organização sobre como executar o GroundRunner como um serviço systemd.

Para configurações básicas, temos os seguintes requisitos de arquivo de unidade systemd para que as atualizações automáticas funcionem corretamente:

Certifique-se de que o executável ExecStart aponta para o binário GroundRunnerMonitor e NÃO para o binário
GroundRunner.
Defina Restart=always.
Não defina StartLimitBurst ou StartLimitIntervalSec, pois eles podem impedir que o GroundRunner reinicie devido a erros transitórios. Se você não quiser que o GroundRunner entre em um loop de reinicialização rápida, pode configurar RestartSec.
Insira systemctl enable para ativar a unidade de serviço systemd do GroundRunner, de modo que ele sobreviva a uma reinicialização.

A Workiva não oferece suporte oficial à execução de um GroundRunner como um processo em primeiro plano. Isso pode ser útil para testar uma configuração, mas, uma vez configurado, o GroundRunner deve ser configurado como um processo de longa duração em segundo plano.

Operando GroundRunners no macOS (somente para testes)

A Workiva oferece suporte aos GroundRunners no macOS somente para fins de teste. Embora os GroundRunners no macOS sejam capazes de executar os mesmos comandos que as versões para Linux e Windows, a Workiva não oferece suporte oficial ao launchd como gerenciador de serviços válido. Isso ocorre porque a Apple encerrou o suporte ao software de servidor macOS em 2022. Laptops e computadores desktop da Apple não são adequados para executar GroundRunners.

Ativar o GroundRunner

Após instalar seu GroundRunner, você deve ativá-lo no Construtor de cadeias.

Na barra lateral do Construtor de cadeias, clique em Conexões.
Clique em Runners na parte superior e, em seguida, em Registro pendente.
Insira um nome curto e descritivo para o runner.
Por exemplo, "<datasource>-GroundRunner".
Se você quiser receber notificações quando o GroundRunner ficar com estado degradado, ative o botão Notificar-me quando este runner ficar com estado degradado para "Ativado" (fica azul).
Clique em Ativar.

Lista de verificação de configuração do GR

Você está executando o executável GroundRunnerMonitor (em vez do executável GroundRunner)?
Você configurou seu GroundRunnerMonitor como um serviço reiniciável em nível de sistema?
- Para Linux: Systemd.
- Para Windows: Serviços do Windows.
Seu serviço reinicia ao reiniciar o sistema?
- No Linux: systemctl enable.
- No Windows: tipo de inicialização definido como Automático.
Você está executando em um sistema operacional de servidor compatível?
Você tem as notificações do GroundRunner ativadas?

Atualização manual de um GroundRunner

Embora raramente seja necessário, talvez você precise atualizar manualmente um GroundRunner.
Consulte a página de suporte da Workiva Atualização manual do GroundRunner para obter instruções sobre como fazer isso.

Desinstalar um GroundRunner

Se você não precisar mais de um GroundRunner, poderá desinstalá-lo.

Nas configurações do Windows, acesse Aplicativos e recursos, selecione GroundRunner (64 bits) e clique em Desinstalar.

Pare o serviço do GroundRunner.
- Se estiver sendo executado como serviço, use o Gerenciador de Serviços do Windows ou insira
  sc stop GroundRunner em uma janela de comando.
- Se estiver sendo executado como processo em primeiro plano, pressione Ctrl+C.
Na caixa de diálogo de comando, como administrador, insira
installer.exe uninstall.
Exclua o diretório executável do GroundRunner.

Na caixa de diálogo de comando, pare o serviço do GroundRunner e exclua seu diretório executável (por exemplo, /home/<username>/wdata/Contents).

Instalar um JRE personalizado

Se necessário, você pode instalar seu próprio JRE para dar suporte a um GroundRunner. A versão do Java deste JRE deve corresponder à versão exigida pelo GroundRunner. Exceto pelos GroundRunners Oracle Essbase e Oracle Hyperion Financial Management (HFM), todos os GroundRunners usam a mesma versão do JRE.

Para obter informações sobre como instalar um JRE personalizado, consulte Desativar bibliotecas compartilhadas da Workiva.

Configurações do GroundRunner e domínios de saída

Para habilitar a comunicação com sua fonte de dados, talvez seja necessário abrir portas de firewall no servidor onde o GroundRunner está instalado. Para alterar as definições de configuração de alguns GroundRunners, você pode editar o arquivo GroundRunner.config no diretório em que os binários estão instalados.

Configuração	Configurações
PORTA	0 a 65535. Por padrão, os GroundRunners usam a porta 8821 para se comunicar entre si. No entanto, uma porta só é necessária se os GroundRunners em servidores diferentes compartilharem saídas de comandos dentro da sua rede.
COMPANY_TOKEN	Deixe como padrão, a menos que o GroundRunner esteja configurado para um locatário diferente.
LOG_LEVEL	Informações ou debug
PROTOCOL	Deixar como padrão.
HTTP_PROXY_URL	Se estiver usando um servidor proxy, insira sua URL e porta (se necessário). Por exemplo, `http://yourproxy:3000` Observação: Os GroundRunners podem usar servidores proxy, mas não aqueles autenticados via New Technology LAN Manager (NTLM). Em vez disso, permita o endereço IP do servidor.
LONG_POLL	Se você estiver usando um servidor proxy, defina como true para instruir o executor a usar o long-polling para recuperar comandos. Para garantir o desempenho, use o rastreamento longo somente se os soquetes da Web não forem compatíveis com o seu servidor proxy ou firewall.
NO_PROXY	Para ignorar o servidor proxy, forneça uma lista separada por vírgulas de hosts para acessar diretamente. Para incluir vários hosts com base em um padrão comum, use o curinga *.
GROUNDRUNNER_CERT	Necessário se estiver usando mais de um GroundRunner e quiser enviar informações criptografadas para o segundo GroundRunner. Deve ser usado em conjunto com PORT. Você também deve especificar o campo PROTOCOL como HTTPS ao ativar o runner.
GROUNDRUNNER_CERT_KEY	Necessário se estiver usando mais de um GroundRunner e quiser receber informações criptografadas de um segundo GroundRunner. Também deve ser usado em conjunto com PORT.
DISABLE_WEBSOCKETS	Os websockets são necessários para executar as transformações. Quando desativado, todos os comandos que usam transformações serão ignorados completamente.

Observação: Seu certificado autoassinado deve ter um Subject Alternative Name (SAN). Se não tiver, quando o seu GroundRunner tentar baixar arquivos, será exibida uma mensagem de erro referenciando o SAN ausente.

Se sua rede precisar permitir domínios de saída, estes se aplicam aos GroundRunners:

Domínio	Finalidade
`h.app.wdesk.com` `h.apac.wdesk.com` `h.ca.wdesk.com` `h.eu.wdesk.com`	Os principais subdomínios para serviços comuns da Workiva, incluindo o Wdata.
`*.wdesk.com`	O domínio principal da plataforma Workiva de produção.
`..wdesk.com`	Os subdomínios para componentes de suporte na plataforma Workiva.

Se você não puder usar curingas (*) para permissões de lista de permissões, use o domínio "mothership" para sua região a fim de permitir o download de recursos do GroundRunner e evitar possíveis problemas de bloqueio no futuro.

Domínio	Finalidade
`mothership.app.wdesk.com` `mothership.apac.wdesk.com` `mothership.ca.wdesk.com` `mothership.eu.wdesk.com`	O subdomínio para baixar os recursos de cadeia necessários.

Segurança

Os GroundRunners nunca coletam ou agregam dados; eles retêm dados somente durante a transmissão. Um certificado de validação estendida (EV) sempre criptografa e protege o tráfego entre um GroundRunner e sua fonte de dados via DigiCert®.

Observação: Para proteger os dados locais, os CloudRunners podem compartilhar a saída com os GroundRunners, mas os GroundRunners não podem compartilhar saídas de arquivos com o CloudRunner.

Solucionar erros do GroundRunner

Se você receber esses erros quando uma cadeia for executada, verifique os GroundRunners do comando.

Dica: Para facilitar a solução de problemas, você pode criar uma cadeia para baixar automaticamente o arquivo de registro do GroundRunner para uma tabela.

Mensagem de erro	Causa	Resolução
Falha ao se comunicar com o agente - este comando não foi executado	O comando não pôde se comunicar com seu GroundRunner. Se isso acontecer, o GroundRunner não foi iniciado ou ocorreu uma interrupção de rede entre o GroundRunner e o Chain Builder.	Verificar O serviço do GroundRunner está funcionando. O servidor do GroundRunner está conectado à Internet.
Não foi possível fazer o download dos recursos associados ao comando. Entre em contato com o Suporte se o erro persistir.	Os executores associados a esses comandos da cadeia não podem se comunicar uns com os outros. Isso geralmente ocorre quando os comandos usam executores diferentes e o CloudRunner está tentando usar uma saída de arquivo de um comando baseado no GroundRunner.	Use o mesmo executor com todos os comandos da cadeia. Se os comandos da cadeia exigirem vários runners, verifique se nenhum comando com GroundRunners passa saídas de arquivos para comandos que usam o CloudRunner.
Erro ao iniciar o comando: `exec: \"\\[connector].exe\": o arquivo não existe" commandExecutorId=[ID]`	Um aplicativo antivírus ou antimalware identificou incorretamente o conector e interceptou sua comunicação com o GroundRunner.	Exclua o diretório de instalação do GroundRunner das verificações do aplicativo.
Erros de certificado	Como usar certificados autoassinados	Em muitos casos, será conveniente usar certificados autoassinados para criptografar a comunicação do GroundRunner. Se estiver usando um certificado autoassinado, certifique-se de que o Nome comum do certificado corresponde à URL pela qual o servidor pode ser acessado. Por exemplo, se o seu GroundRunner estiver ouvindo na porta 8821 e você puder acessar o servidor da sua rede via `localhost`, o Nome comum do certificado seria "`localhost`".
Falha intermitente na cadeia com erro: "Connection reset by peer"	Quando vários runners são instalados na mesma máquina, cada um deve ter um GUID único. Se o mesmo GUID for usado, os executores poderão se sobrepor e entrar em um loop de atualização, causando falhas ocasionais na cadeia.	Recomendamos uma reinstalação completa do GroundRunner.
Os comandos são ignorados no GroundRunner, mas são bem-sucedidos no CloudRunner	Os websockets são necessários para executar as transformações. Quando os websockets estão desativados, todas as transformações serão ignoradas completamente.	Abra seu arquivo de configuração e defina `DISABLE_WEBSOCKETS=false`.
Erro ao ler do socket. `Tentando novamente/repetir a conexão: read tcp <IP>:<Port>-><IP>:<Port>: wsarecv: Uma tentativa de conexão falhou porque a parte conectada não respondeu adequadamente após um tempo, ou a conexão estabelecida falhou porque o host conectado não respondeu.`	Problema interno de firewall ou rede	Acione sua equipe interna de TI ou rede para revisar os logs e a configuração a fim de resolver o erro.
read <IP>:<Port>-><IP>:<Port>: `wsarecv: Uma conexão existente foi fechada à força pelo host remoto`	Problema interno de firewall ou rede	Peça à sua equipe interna de TI ou de rede para revisar os logs e a configuração a fim de resolver o erro.

Recursos adicionais

Suporte

Comunidade

Centro de suporte da Workiva