Implantação com Docker¶

O Drovio Server pode ser implantado em contentor Docker. Fornecemos para isso duas imagens distintas:

Tudo-em-um: destinada sobretudo ao ensaio e à pré-produção. Contém as funcionalidades essenciais do Drovio Server. Todas as dependências estão integradas e são configuradas automaticamente no arranque do contentor.
Produção: reservada aos ambientes de produção. O Drovio Server apoia-se numa base gerida pelo Docker ou externa, e no arquivo de sessões interno ou num arquivo Redis gerido pelo Docker ou externo.

Imagem Docker	Tudo-em-um	Produção
Utilização	Teste e pré-produção	Produção
Base	Debian 13 (Trixie) slim	Debian 13 (Trixie) slim
Base PostgreSQL	Base PostgreSQL interna	Base PostgreSQL gerida pelo Docker ou externa, 14 e superior
Arquivo de sessões	Arquivo interno	Arquivo interno, ou arquivo Redis gerido pelo Docker ou externo
Corre sob	`root`	`drovio`, uid 1000

Componentes geridos pelo Docker ou externos

O termo gerido pelo Docker designa um componente do Drovio Server conduzido pelo plugin docker compose e residente na mesma rede Docker. Os componentes externos são, pelo contrário, totalmente independentes: deve então fornecer as suas informações de ligação através das variáveis de ambiente correspondentes.

As duas imagens são multiarquitetura: linux/amd64 e linux/arm64 são servidas sob o mesmo nome, e o Docker retém aquela que corresponde à sua máquina. Não há qualquer opção --platform a passar, nem nome de imagem próprio de uma arquitetura.

Requisitos¶

Docker Engine 20.10 ou superior, para o suporte das imagens multiarquitetura.
O plugin docker compose 2.20 ou superior para a imagem de produção, que utiliza os perfis e as dependências facultativas.

Obter as imagens¶

As imagens são publicadas no nosso registo privado. Peça as credenciais da sua organização a support@drovio.com: receberá um nome de utilizador e um token, ambos próprios de si e revogáveis.

Imagem	Referência
Tudo-em-um	`registry.gitlab.com/drovio/drovio-server-aio`
Produção	`registry.gitlab.com/drovio/drovio-server`

docker login registry.gitlab.com -u <username> -p <token>
docker pull registry.gitlab.com/drovio/drovio-server:3.6.9

Que etiqueta utilizar¶

Etiqueta	Designa
`3.6.9`	esta versão exata, e nunca se move
`3.6`	a última correção da série 3.6
`latest`, `stable`	a última versão publicada

Fixe uma versão completa em produção. As etiquetas móveis prestam serviço para um ensaio, mas fazem com que um docker compose pull possa trazer uma nova versão menor sem que o tenha decidido.

Acesso à rede de saída

A sua firewall deve autorizar registry.gitlab.com assim como o domínio de armazenamento de objetos de onde as camadas de imagem são descarregadas. Um docker login que funciona seguido de um docker pull que se atola vem quase sempre daí.

Instalação sem ligação¶

Se os seus servidores não tiverem qualquer acesso de saída, entregamos igualmente cada versão sob a forma de arquivo, um por arquitetura. Peça-o ao suporte e carregue-o depois na máquina alvo:

docker load -i docker-drovio-server-amd64-3.6.9.tar.gz

A imagem assim carregada tem o mesmo nome e a mesma etiqueta que a do registo: o resto desta página aplica-se, portanto, tal e qual.

Gestão dos dados persistentes¶

Em conformidade com os princípios do Docker, os dados armazenados num contentor são efémeros e não sobrevivem à sua destruição. Existem, no entanto, mecanismos para os dados persistentes, entre os quais as montagens ligadas, que projetam um ficheiro ou uma pasta do sistema anfitrião para o interior do contentor.

As nossas imagens Docker apoiam-se em montagens ligadas para três tipos de dados persistentes:

Dados	Caminho no contentor	Diz respeito a
Ficheiros de configuração	`/etc/drovio-server`	as duas imagens
Ficheiros de registo	`/var/log/drovio-server`	as duas imagens
Dados da base	`/opt/drovio-server/data`	a imagem tudo-em-um

A imagem de produção não integra qualquer base. Só precisa dos dois primeiros. A localização dos seus dados é assunto da base para a qual a aponta, quer se trate daquela que o docker compose inicia por si ou do seu próprio servidor.

O segredo JWT vive na pasta de configuração

No primeiro arranque, o contentor escreve em settings.conf um segredo JWT próprio. Este segredo assina as sessões dos utilizadores. Remover essa pasta faz perder o segredo: cada utilizador terá de iniciar sessão novamente.

Proprietário das pastas, imagem de produção¶

A imagem de produção corre sob o utilizador não privilegiado drovio, uid e gid 1000. As duas pastas nas quais escreve devem pertencer-lhe:

mkdir -p config logs
sudo chown -R 1000:1000 config logs

Sem isso o contentor recusa arrancar, indicando que pasta corrigir.

Nunca faça isto na pasta da base

data/postgresql pertence ao contentor da base de dados, que corre sob o seu próprio utilizador. Entregá-la ao uid 1000 impede o PostgreSQL de arrancar, com um erro de permissão sobre os seus próprios ficheiros.

Subida a partir da 3.6.5 ou anterior

As versões anteriores desta imagem corriam sob root. As pastas que criaram no seu anfitrião pertencem, portanto, a root. Lance o comando chown acima nas suas pastas config e logs existentes antes de iniciar a nova imagem.

Nada é escrito fora destes dois caminhos e da pasta de trabalho do Vert.x sob /tmp. O contentor pode, aliás, correr com um sistema de ficheiros raiz apenas de leitura:

docker run --read-only --tmpfs /tmp ...

Implantar a imagem tudo-em-um¶

Crie uma pasta drovio-server e coloque-se dentro dela:

mkdir drovio-server
cd drovio-server

Crie um volume para a base integrada, depois lance o contentor:

docker volume create drovio-data

docker run --hostname drovio.example.com \
  -p 8090:8090 \
  -v "./config:/etc/drovio-server" \
  -v "./logs:/var/log/drovio-server" \
  -v "drovio-data:/opt/drovio-server/data" \
  --rm -it "registry.gitlab.com/drovio/drovio-server-aio:3.6.9"

Utilize um volume para a base, não uma montagem ligada

O PostgreSQL verifica que a sua pasta de dados pertence ao utilizador postgres. Ora o Docker Desktop, tanto em macOS como em Windows, apresenta tudo o que se encontra numa montagem ligada como pertencente a root, faça o que fizer. O contentor não consegue arrancar assim. Um volume nomeado não tem esta limitação, e é de qualquer forma a maneira recomendada de conservar dados de base. A configuração e os registos não são afetados e podem permanecer em montagens ligadas.

Opção	Descrição
`--hostname`	Fixa um nome de anfitrião preciso. Terá em seguida de no-lo comunicar para que geremos as suas licenças. Conserve sempre o mesmo, estando as licenças ligadas a ele.
`-p <anfitrião>:<contentor>`	Publica a porta do contentor na porta do anfitrião. A porta `8090` é aqui utilizada, uma vez que o Drovio Server não ativa o TLS e todo o tráfego HTTP passa por esta porta por predefinição.
`-v "<anfitrião>:<contentor>"`	Montagens ligadas para os dados persistentes descritos acima.
`--rm`	Elimina automaticamente o contentor ao pará-lo.
`-it`	Aloca um pseudoterminal ligado à entrada padrão do contentor.

O nome de anfitrião só é escrito uma vez

No seu primeiro arranque, o servidor inscreve na sua configuração o seu próprio URL, construído a partir do nome de anfitrião que lhe dá. Não é recalculado em seguida, e as suas licenças estão ligadas a ele. Um contentor iniciado sem --hostname recusaria funcionar.

Preencha antes APP_URL se o URL pelo qual os seus utilizadores acedem ao servidor diferir do nome de anfitrião do contentor, atrás de um proxy inverso por exemplo.

Implantar a imagem de produção¶

A imagem de produção implanta-se com o plugin docker compose, a ferramenta que serve para definir e lançar aplicações Docker multicontentor.

Recuperar os ficheiros de implantação¶

Tudo aquilo de que precisa para implantar encontra-se na própria imagem. Extraia-o para o local onde quer fazer correr o servidor, com as credenciais que lhe serviram para a recuperar:

id=$(docker create registry.gitlab.com/drovio/drovio-server:3.6.9)
docker cp "$id:/opt/drovio-server/bundle/." ./drovio-server
docker rm "$id"
cd drovio-server

Obtém três ficheiros, todos ajustados à versão que acabou de recuperar:

Ficheiro	O que é
`docker-compose.yml`	a implantação, com ou sem base e arquivo de sessões geridos
`env.example`	as definições que deve preencher
`drovio-server.sql`	o esquema da base, utilizado na sua criação e nas atualizações

A sua linha image: designa já a versão exata da qual o extraiu.

Definições¶

Copie env.example para .env e preencha-o. Dois valores são obrigatórios:

DROVIO_HOSTNAME=drovio.example.com
DB_PASSWORD=<generate one>

Gere as palavras-passe em vez de reutilizar uma, por exemplo com openssl rand -base64 24. DROVIO_HOSTNAME segue a mesma regra que --hostname acima: só é inscrito no URL do servidor no primeiro arranque.

Componentes geridos pelo Docker ou externos¶

A escolha entre uma base e um arquivo de sessões geridos aqui ou fornecidos por si faz-se no arranque, pelos perfis. O mesmo docker-compose.yml cobre os três casos:

Comando	O que isso lança
`docker compose --profile bundled-db up`	PostgreSQL gerido pelo `docker compose`, arquivo de sessões interno
`docker compose --profile bundled-db --profile redis up`	idem, com um arquivo de sessões Redis gerido pelo `docker compose`
`docker compose up`	base externa, preencha `DB_HOST` e as variáveis associadas em `.env`

Com o perfil redis, descomente igualmente SS_TYPE, SS_REDIS_CONNECTION_STRINGS, SS_REDIS_MASTER_NAME e SS_REDIS_PASSWORD no seu .env.

Componentes geridos pelo Docker: conduzidos pelo plugin docker compose. Todos os contentores seguem o mesmo ciclo de vida e partilham a mesma rede Docker.
Componentes externos: não são declarados no ficheiro docker-compose. As suas informações de ligação devem ser transmitidas através das variáveis de ambiente previstas para esse efeito. No primeiro arranque, o ficheiro de configuração do Drovio Server não existe e é criado com valores predefinidos. Estas variáveis servem então para substituir alguns deles, o que permite um primeiro arranque bem-sucedido.

Verificar que o servidor responde¶

As duas imagens expõem um ponto de verificação de saúde e declaram um HEALTHCHECK Docker que dele se serve. O docker ps apresenta o contentor como healthy assim que o servidor responde.

curl -f http://drovio.example.com:8090/healthcheck

Variáveis de ambiente¶

Variável de ambiente	Campo de configuração
`APP_URL`	`.http.url`
`SS_TYPE`	`.http.session_store.type`
`SS_REDIS_CONNECTION_STRINGS`	`.http.session_store.redis.connections`
`SS_REDIS_MASTER_NAME`	`.http.session_store.redis.master`
`SS_REDIS_PASSWORD`	`.http.session_store.redis.password`
`DB_HOST`	`.database.host`
`DB_PORT`	`.database.port`
`DB_NAME`	`.database.database`
`DB_USER`	`.database.user`
`DB_PASSWORD`	`.database.password`
`DB_MAIN_POOL_SIZE`	`.database.pool_options.main.max_size`
`DB_LICENSING_POOL_SIZE`	`.database.pool_options.licensing.max_size`
`DB_MAIN_IDLE_TIMEOUT`	`.database.pool_options.main.idle_timeout`
`DB_LICENSING_IDLE_TIMEOUT`	`.database.pool_options.licensing.idle_timeout`
`DB_MAIN_CONNECT_TIMEOUT`	`.database.pool_options.main.connect_timeout`
`DB_LICENSING_CONNECT_TIMEOUT`	`.database.pool_options.licensing.connect_timeout`
`DB_POOL_SIZE` (deprecated)	`.database.pool_options.main.max_size`
`DB_NV_POOL_SIZE` (deprecated)	`.database.pool_options.licensing.max_size`
`DB_IDLE_TIMEOUT` (deprecated)	`.database.pool_options.main.idle_timeout`

As variáveis de ambiente prevalecem sempre

Estas variáveis substituem sistematicamente os valores do ficheiro de configuração do Drovio Server no arranque. Se alterar nos ficheiros de configuração um valor associado a uma delas, deve também retirar essa variável do ficheiro docker-compose ou atualizar o seu valor antes de reiniciar o Drovio Server.

Atualizar¶

Recupere a versão pretendida, depois recrie os contentores. A sua configuração, os seus registos e a sua base vivem nas montagens ligadas e não são afetados.

docker compose pull
docker compose --profile bundled-db up -d

Atualizar o esquema da base de dados¶

Uma nova versão pode adicionar tabelas ou colunas. As duas imagens não tratam este ponto da mesma forma.

Imagem	O que aplica as evoluções de esquema
Tudo-em-um	o próprio contentor, a cada arranque. Nada a fazer.
Produção	você, antes de iniciar a nova imagem.

A imagem de produção nunca toca no seu esquema. O drovio-server.sql só é executado na criação da base, pelo contentor de base do docker compose no seu primeiro arranque, ou por si no seu próprio servidor. Não é repetido em seguida.

Ao subir de versão da imagem de produção:

Extraia drovio-server.sql da imagem para a qual sobe, como para uma primeira instalação. O script entregue numa imagem é sempre aquele que essa imagem espera.
```
id=$(docker create registry.gitlab.com/drovio/drovio-server:3.6.9)
docker cp "$id:/opt/drovio-server/bundle/drovio-server.sql" .
docker rm "$id"
```

Aplique-o à sua base, com os contentores do Drovio Server parados.

psql -h my-database.example.com -U drovio -d drovio -f drovio-server.sql

Inicie a nova imagem.

O script está escrito para ser repetido: cria o que falta e deixa o resto no seu lugar, de forma que aplicá-lo a uma base já atualizada nada muda.

Faça primeiro uma cópia de segurança

Faça uma cópia de segurança da base antes de aplicar um script de esquema, seja qual for a diferença de versão. É o único passo deste procedimento que não se recupera.

Tudo-em-um e versões maiores do PostgreSQL

A imagem tudo-em-um não atualiza o seu cluster de base de dados no lugar. Se uma nova versão integrar uma versão maior do PostgreSQL mais recente, o contentor para no arranque com uma mensagem explicativa. Exporte os seus dados a partir da imagem anterior com pg_dumpall, depois restaure-os num volume novo com a nova.

Migrar da imagem production-ready v3.6.5 ou anterior¶

Os deployments production-ready anteriores à 3.6.6 só podiam ser carregados a partir de um arquivo e corriam como root. Atualizá-los e passá-los para o registo faz-se uma única vez, mas a ordem indicada a seguir é importante.

Faça uma cópia de segurança da sua base de dados. O último passo deste procedimento é o único que não pode ser desfeito.
Altere as permissões dos dois diretórios onde o servidor escreve, e apenas desses. Foram criados por um contentor que corria como root, e a nova imagem corre com uid 1000.
```
sudo chown -R 1000:1000 config logs
```
Não a pasta inteira

Não execute este comando sobre todo o seu diretório de deployment. data/postgresql pertence ao contentor da base de dados, que corre com o seu próprio utilizador, e passá-lo para o uid 1000 impede o PostgreSQL de arrancar.
Aponte para o registo. Substitua a linha image: do seu docker-compose.yml, ou recomece a partir do pacote incluído na nova imagem. O sufixo de arquitetura desaparece: um deployment arm64 que usava drovio/drovio-server-arm64 deve agora usar drovio/drovio-server.
```
image: 'registry.gitlab.com/drovio/drovio-server:3.6.9'
```
Mantenha a palavra-passe da sua base de dados. Se usar o docker-compose.yml incluído e o seu ficheiro .env, DB_PASSWORD tem de conter a palavra-passe que a sua base já usa, a que está escrita no seu ficheiro compose atual. Uma palavra-passe gerada de novo deixaria o servidor sem conseguir ligar-se.
Arranque a nova imagem e verifique que sobe antes de avançar.
Aplique o script de esquema se estiver também a mudar de versão, conforme descrito acima.

Nada mais é reescrito

O URL do seu servidor e as licenças a ele associadas são lidos da configuração que já possui. As regras sobre --hostname só se aplicam a um primeiro arranque. Um deployment existente não é afetado por elas.

Enquanto não tiver executado o passo 6, voltar atrás resume-se a repor a linha image: anterior, desde que tenha guardado o arquivo que carregou originalmente.

Migrar de uma instalação Windows ou por pacote Linux¶

Se instalou o Drovio Server em Windows ou através do pacote Linux correspondente à sua distribuição, e pretende passar para a nossa imagem Docker de produção, há apenas dois elementos a transferir: a base de dados e a pasta de configuração. Nada mais tem de ser recriado, a migração é simples.

Três coisas a saber antes de começar

O URL do seu servidor tem de sobreviver. As suas licenças estão ligadas a esse URL, e portanto a esse nome de anfitrião.

O seu segredo JWT também tem de sobreviver, caso contrário as sessões dos utilizadores autenticados seriam invalidadas.

As variáveis do .env são aplicadas em cada arranque, e não apenas no primeiro. É assim que aponta a sua configuração existente para uma nova base de dados sem a editar à mão.

Faça uma cópia de segurança da base de dados e de toda a pasta de configuração. A reposição do passo 7 é o único passo deste procedimento que não pode ser desfeito.

Pare o serviço.

LinuxWindows

systemctl stop drovio-server

sc stop drovio-server

Exporte a base de dados. O anfitrião, o nome e o utilizador constam da secção database do seu settings.conf.
```
pg_dump -h localhost -U drovio -d drovio -Fc -f drovio.dump
```
Recupere os ficheiros de implantação como para uma primeira instalação, depois copie env.example para .env.
Traga a sua configuração. Copie settings.conf e admin.properties para a pasta config, ao lado de docker-compose.yml, bem como qualquer ficheiro para o qual apontem: keystore TLS, keystore SAML, autoridade de certificação LDAP.

LinuxWindows

Os caminhos contidos em settings.conf já correspondem ao que o contentor espera, sendo ambos /etc/drovio-server. Nada a reescrever.

Cada caminho absoluto contido em settings.conf tem de ser reescrito, de C:\ProgramData\Drovio\Drovio Server\... para /etc/drovio-server/.... Consoante o que utilizar, isto pode dizer respeito a http.keystore, users.auth.saml.keystore, users.auth.saml.sp_metadata_path, users.auth.saml.idp_metadata_path e users.auth.ldap.ca_certificate_path.
Entregue as duas pastas ao utilizador do contentor, ou seja ao uid 1000.
```
mkdir -p logs
sudo chown -R 1000:1000 config logs
```
Reponha a sua exportação, depois preencha o .env.
Base de dados gerida pelo composeA sua própria base de dados
Inicie a base de dados sozinha e deixe-a inicializar. Reponha em seguida a sua exportação. O contentor cria um esquema vazio no seu primeiro arranque: a reposição tem portanto de o substituir e não de se lhe juntar.
docker compose --profile bundled-db up -d database pg_restore -h localhost -U drovio -d drovio --clean --if-exists drovio.dump
No .env, dê ao DB_PASSWORD a palavra-passe com que a base de dados acabou de ser criada.
Reponha no servidor que tenciona conservar, depois aponte a configuração para ele no .env:
DB_HOST=my-database.example.com DB_NAME=drovio DB_USER=drovio DB_PASSWORD=<a palavra-passe existente>
Indique DROVIO_HOSTNAME no .env com o nome pelo qual os seus utilizadores já acedem ao servidor. O compose exige-o, mesmo que não venha a reescrever o seu URL.

Deixe APP_URL vazio

Ao contrário de DROVIO_HOSTNAME, o APP_URL é escrito na configuração em cada arranque. Dar-lhe outro valor que não o URL atual do seu servidor quebraria as licenças que lhe estão ligadas.
Aplique o script de esquema se estiver também a mudar de versão, conforme descrito acima. Uma migração na mesma versão não exige nada aqui.

Inicie o servidor e verifique que consegue aceder-lhe:

docker compose --profile bundled-db up -d
curl -f http://drovio.example.com:8090/healthcheck

Deixe a instalação antiga no lugar, parada, até estar satisfeito. Voltar atrás resume-se então a iniciar de novo o seu serviço, desde que não tenha deixado a nova implantação escrever na mesma base de dados.