Instalando e configurando o CKAN usando Docker Compose

Trecho da documentação oficial Docker Compose setup for CKAN organizado
pela Open Knowledge Foundation e colaboradores.
Traduzido pela Escola de Dados em outubro de 2024.

Por que usar o CKAN?

O CKAN é solução de código aberto usado para catalogar e disponibilizar dados. Este sistema de gerenciamento já foi adotado por diversos governos no mundo
inteiro – como nos Estados Unidos, Suíça, Canadá, Reino Unido, Alemanha e México – e fornece uma plataforma poderosa para catalogar, armazenar e acessar conjuntos de dados. Por ser uma tecnologia de código aberto, o CKAN pode ser utilizado, copiado ou modificado sem qualquer necessidade de pedido de autorização ou pagamento de licenças ou royalties.

A Open Knowledge Brasil, é a pioneira em oferecer formação e serviços de instalação e personalização do CKAN. Pelo curso já passaram servidores públicos da Empresa de Tecnologia da Informação e Comunicação do Município de São Paulo (Prodam), da Secretaria de Planejamento do Governo Estadual da Bahia, do governo de Goiás, do Ministério da Gestão e da Inovação em Serviços Públicos, entre outros.

Por que esse tutorial é importante?

O CKAN conta com uma comunidade engajada de mais de 300 colaboradores ao redor do mundo, que contribuem ativamente com atualizações e novas funcionalidades. Toda documentação (que pode ser conferida no Github) é feita em inglês e, por isso, há poucos tutoriais disponíveis em PT-BR. Esta tradução é uma das iniciativas da Escola de Dados para democratizar o acesso aos conteúdos e aprimorar as práticas de transparência e publicação de dados abertos no Brasil.

Visão Geral

Este é um conjunto de configurações e arquivos para rodar o CKAN.

As imagens do CKAN utilizadas são do repositório ckan-docker do CKAN oficial.

As imagens que não são do CKAN são as seguintes:

DataPusher: Imagem do DataPusher pré-configurada do CKAN;
PostgreSQL: Imagem oficial do PostgreSQL. Os arquivos do banco de dados são armazenados em um volume nomeado;
Solr: Imagem do Solr pré-configurada do CKAN. Os dados do índice são armazenados em um volume nomeado;
Redis: imagem padrão do Redis;
NGINX: imagem estável mais recente do nginx que inclui pontos de extremidade SSL e Não-SSL.

O site é configurado usando variáveis de ambiente que você pode definir no arquivo .env.

Instalando o Docker

Instale o Docker seguindo as orientações da documentação oficial (em inglês).

Para verificar se a instalação foi bem-sucedida do Docker, execute docker run hello-world e docker version. Esses comandos devem exibir as versões para cliente e servidor.

docker compose vs docker-compose

Todos os comandos do Docker Compose nesta documentação usarão a versão V2 do Compose, ou seja: docker compose. A versão mais antiga (V1) usava o comando docker-compose. Para mais informações, leia o trecho Migrar para Compose V2 (em inglês) na documentação.

Instalar (compilar e executar) CKAN mais dependências

Modo básico

Use este modo se você é um mantenedor e não fará alterações no código ou extensões do CKAN.

Copie o arquivo .env.example incluído e renomeie-o para .env. Modifique-o de acordo com suas próprias necessidades.

Observe que ao acessar o CKAN diretamente (por meio de um navegador), ou seja, sem passar pelo NGINX, você precisará garantir que “ckan” esteja configurado como um alias para localhost no arquivo de hosts locais ou você precisará alterar a entrada .env para CKAN_SITE_URL.

Usar os valores padrão no arquivo .env.example resultará em uma instância do CKAN funcional. Há um usuário sysadmin criado por padrão com os valores definidos em CKAN_SYSADMIN_NAME e CKAN_SYSADMIN_PASSWORD (ckan_admin e test1234 por padrão). Obviamente, isso deve ser alterado antes de executar esta configuração como uma instância pública do CKAN.

Para construir as imagens use o comando:

docker compose build

Para iniciar os contêineres:

docker compose up

Isso iniciará os contêineres na janela atual. Por padrão, os contêineres registrarão diretamente nesta janela, cada um usando uma cor diferente. Você também pode usar a opção -d “modo desanexado”, ou seja docker compose up -d se desejar usar a janela atual para outra coisa.

Ao final da sequência de inicialização do contêiner, devem estar sendo executados 6 deles:

Após esta etapa, o CKAN deve estar rodando em CKAN_SITE_URL.

Modo Desenvolvedor

Use este modo se você está fazendo alterações no código do CKAN, criando novas extensões ou fazendo alterações no código de extensões existentes. Este modo também usa o arquivo .env para opções de configuração.

Para desenvolver extensões locais, use o arquivo docker-compose.dev.yml.

Para construir as imagens use o comando:

docker compose -f docker-compose.dev.yml build

Para iniciar os contêineres:

docker compose -f docker-compose.dev.yml up

Mais a frente veremos mais detalhes de como funcionam na sessão Imagens do CKAN.

Criando uma extensão

Você pode usar as instruções de extensão (em inglês) da documentação oficial do CKAN para criar uma extensão, executando o comando apenas dentro do contêiner e configurando a pasta src/ montada como saída:

docker compose -f docker-compose.dev.yml exec ckan-dev /bin/sh -c "ckan -c /srv/app/ckan.ini generate extension --output-dir /srv/app/src_extensions"

Os novos arquivos e diretórios da extensão são criados na pasta /srv/app/src_extensions/ dentro do contêiner em execução. Eles também existirão no diretório local src/ já que este está montado como /srv/app/src_extensions/ no contêiner do CKAN. Você pode precisar alterar o proprietário da pasta para ter as permissões adequadas.

Executando HTTPS no modo de desenvolvimento

Às vezes é útil executar sua instância de desenvolvimento local sob HTTPS, por exemplo, se você estiver usando extensões de autenticação como ckanext-saml2auth.

Para ativá-lo, defina o seguinte no seu arquivo .env:

USE_HTTPS_FOR_DEV=true

E atualize a configuração de URL do site:

CKAN_SITE_URL=https://localhost:5000

Após recriar o contêiner ckan-dev, você deve ser capaz de acessar o CKAN em https://localhost:5000.

Depuração Remota com VS Code

O Visual Studio Code é um IDE gratuito que inclui depuração remota para aplicações Python. Para depurar o CKAN, você deve habilitar o debugpy para sua instância de desenvolvimento no seu arquivo .env:

USE_DEBUGPY_FOR_DEV=true

Em seguida inicie os contêineres no modo de desenvolvimento e abra o VS Code.

No VS Code:

Instale a extensão “Dev Container”: pressione CTRL+SHIFT+X, digite dev container, clique em instalar.
Clique no botão Open a Remote Window (Abrir uma Janela Remota) no canto inferior esquerdo da janela do VS Code.
Clique em Attach to Running Container… e selecione seu contêiner ckan-dev, por exemplo, ckan-docker-ckan-dev-1.
Clique no ícone Run and Debug (Executar e Depurar) no painel esquerdo, depois em create a launch.json (criar um launch.json), selecione Python Debugger (Depurador Python), Remote Attach (Anexar Remotamente), host localhost (host local) e porta 5678.
Pressione F5 ou clique no menu Run e em Start Debugging (Iniciar Depuração).

Agora você pode definir pontos de interrupção e depurar remotamente sua instância de desenvolvimento do CKAN.

Atualizando o arquivo de ambiente para o modo de desenvolvimento

O arquivo de ambiente Docker Compose .env está configurado por padrão para o modo de produção. Algumas mudanças são necessárias se você deseja rodar no modo de desenvolvimento:

Altere a variável CKAN_SITE_URL para ser http://localhost:5000
Atualize a variável CKAN__DATAPUSHER__CALLBACK_URL_BASE para usar o nome do contêiner ckan-dev: http://ckan-dev:5000
Atualize a variável DATAPUSHER_REWRITE_URL para também usar o nome do contêiner ckan-dev: http://ckan-dev:5000

Imagens do CKAN

Fonte: tradução da imagem da documentação original pela Escola de Dados, 2024.

Os arquivos de configuração da imagem Docker usados para construir seu projeto CKAN estão localizados na pasta ckan/. Há dois arquivos Docker:

Dockerfile: baseado em ckan/ckan-base:<versão>, uma imagem base localizada no repositório DockerHub, que possui o CKAN instalado juntamente com todas as suas dependências, devidamente configurado e funcionando no uWSGI (configuração de produção);
Dockerfile.dev: baseado em ckan/ckan-base:<versão>-dev, também localizado no repositório DockerHub, e estende ckan/ckan-base:<versão> para incluir:
1. Qualquer extensão clonada na pasta src será instalada no contêiner CKAN quando o Docker Compose for iniciado (docker compose up). Isso inclui a instalação de quaisquer requisitos listados em um arquivo requirements.txt (ou pip-requirements.txt) e a execução do comando python setup.py develop;
2. CKAN é iniciado executando o seguinte comando: /usr/bin/ckan -c /srv/app/ckan.ini run -H 0.0.0.0;
3. Certifique-se de adicionar os plugins locais ao CKAN__PLUGINS variável de ambiente no arquivo .env;
4. Quaisquer alterações personalizadas nos scripts executados durante a inicialização do contêiner podem ser feitas nos scripts na diretório setup/. Por exemplo, se você quiser alterar a porta na qual o CKAN é executado, será necessário fazer alterações no arquivo Docker Compose yaml e no arquivo start_ckan.sh.override. Então você precisaria adicionar a seguinte linha ao Dockerfile, por exemplo: COPY setup/start_ckan.sh.override ${APP_DIR}/start_ckan.sh. O arquivo start_ckan.sh na imagem construída localmente sobrescreveria o arquivo start_ckan.sh incluído na imagem base.

Estendendo as imagens de base

As imagens de base do CKAN são construídas a partir do CKAN Docker images.

Você pode modificar os arquivos Docker para criar sua própria imagem personalizada, adaptada ao seu projeto, instalando quaisquer extensões e requisitos extras necessários. Aqui é onde você atualizaria para usar uma imagem base CKAN diferente, por exemplo: ckan/ckan-base:<new version>

Para realizar etapas adicionais de inicialização, você pode adicionar scripts à sua imagem personalizada e copiá-los para a pasta /docker-entrypoint.d (A pasta deve ser criada para você quando você construir a imagem). Qualquer arquivo com extensão *.sh e *.py nessa pasta será executado logo após o script principal de inicialização (prerun.py) ser executado e antes dos processos do servidor web e do supervisor serem iniciados.

Por exemplo, considere a seguinte imagem personalizada:

Queremos instalar uma extensão como ckanext-validation que precisa criar tabelas no banco de dados no momento da inicialização. Criamos um script setup_validation.sh em uma pasta docker-entrypoint.d com os comandos necessários:

E então, no nosso arquivo Dockerfile.dev, nós instalamos a extensão e copiamos os scripts de inicialização:

OBS: Há diversos exemplos de extensões comentadas no arquivo Dockerfile.dev.

Aplicando correções

Ao construir suas imagens específicas do projeto CKAN (as definidas na pasta ckan/), você pode aplicar correções ao núcleo do CKAN ou a qualquer uma das extensões construídas. Para fazer isso, crie uma pasta dentro de ckan/patches com o nome do pacote a ser corrigido (por exemplo, ckan ou ckanext-??). Dentro dessa pasta, você pode colocar arquivos de correção (patch) que serão aplicados durante a construção das imagens. As correções serão aplicadas em ordem alfabética, então você pode prefixá-las sequencialmente se necessário.

Por exemplo, verifique a seguinte pasta de exemplo de imagem:

Depuração com o pdb

Adicione estas linhas ao serviço ckan-dev no arquivo docker-compose.dev.yml

stdin_open: true

tty: true

Depurar com o pdb (exemplo) – Interagir com docker attach $(docker container ls -qf name=ckan)

Comando:

python -m pdb /usr/lib/ckan/venv/bin/ckan --config /srv/app/ckan.ini run --host 0.0.0.0 --passthrough-errors

Datastore and datapusher

O banco de dados do Datastore e o usuário são criados como parte dos scripts de entrypoint para o contêiner db. Há também um contêiner Datapusher executando a última versão do Datapusher.

NGINX

A configuração base do Docker Compose usa uma imagem NGINX como front-end (ou seja, proxy reverso). Ela inclui HTTPS executando na porta número 8443. Um certificado SSL “autoassinado” é gerado como parte do ENTRYPOINT.

A diretiva server_name do NGINX e o campo CN no certificado SSL foram ambos definidos como ‘localhost’. Isso obviamente não deve ser usado para produção.

Criando os arquivos de certificado SSL e chave da seguinte maneira:

openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 -subj "/C=DE/ST=Berlin/L=Berlin/O=None/CN=localhost" -keyout ckan-local.key -out ckan-local.crt

O arquivos ckan-local.* precisarão ser movidos para o diretório nginx/setup/.

ckanext-envvars

A extensão ckanext-envvars é utilizada no repositório base Docker do CKAN para construir as imagens base. Esta extensão verifica variáveis de ambiente que seguem um formato esperado e atualiza as configurações correspondentes com seus valores.

Para que a extensão identifique corretamente quais chaves de variáveis de ambiente correspondem ao formato usado para o objeto de configuração, as chaves de variáveis de ambiente devem ser formatadas da seguinte maneira:

Todas as letras maiúsculas;
Substituir pontos (‘.’) por dois sublinhados (‘__’);
As chaves devem começar com ‘CKAN’ ou ‘CKANEXT’, se não começarem, você pode adicioná-las ao início com ‘CKAN___’.

Por exemplo:

• CKAN__PLUGINS="envvars image_view text_view recline_view datastore datapusher"

• CKAN__DATAPUSHER__CALLBACK_URL_BASE=http://ckan:5000

• CKAN___BEAKER__SESSION__SECRET=CHANGE_ME

Estes parâmetros podem ser adicionados ao arquivo .env.

Para mais informações consulte a documentação da extensão ckanext-envvars.

CKAN_SITE_URL

Por conveniência, o parâmetro CKAN_SITE_URL deve ser definido no arquivo .env. Para desenvolvimento, ele pode ser configurado como http://localhost:5000 e para ambientes que não são de desenvolvimento como https://localhost:8443.

Gerenciar novos usuários

Crie um novo usuário a partir do host Docker. Por exemplo, para criar um novo usuário chamado ‘admin’ você pode usar o seguinte comando:

docker exec -it ckan -c ckan.ini user add admin email=admin@localhost

Para deletar o usuário ‘admin’:

docker exec -it <container-id> ckan -c ckan.ini user remove admin
Crie um novo usuário dentro do contêiner do CKAN. Você precisará obter uma sessão no contêiner em execução:

ckan -c ckan.ini user add admin email=admin@localhost

Para deletar o usuário ‘admin’:

ckan -c ckan.ini user remove admin

Alterando a imagem base

A imagem base usada no CKAN Dockerfile e Dockerfile.dev pode ser alterada para que uma imagem diferente do DockerHub seja utilizada, por exemplo ckan/ckan-base:2.10.5 pode ser usada em vez de ckan/ckan-base:2.11.0.