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.6

Que etiqueta utilizar¶

Etiqueta	Designa
`3.6.6`	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.6.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.

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.6"

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.6)
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

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.6)
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.