Prezados leitores,
Sempre que preciso instalar uma nova instância do GeoNode, sigo os procedimentos que já compartilhei aqui no blog:
– Instalação do GeoNode 5 no Ubuntu 24.04
– Instalação do Certificado SSL no GeoNode
– Atualizar camadas do GeoServer para o GeoNode automaticamente
O passo a passo ajuda bastante, mas, a cada instalação, lá estava eu novamente: preparando o servidor, instalando dependências, criando o projeto, ajustando configurações e habilitando o HTTPS.
Ao preparar um ambiente para mais um curso, pensei: por que não automatizar esse processo?
A ideia foi transformar essa sequência em um instalador reutilizável. Agora, basta preencher um arquivo de configuração e executar um comando para iniciar a instalação.
Testei o procedimento em uma máquina nova, utilizando o GeoNode 5.1.0, e o resultado foi a aplicação funcionando com HTTPS habilitado.
Vamos ver como utilizar!
1. O que o instalador faz?
O instalador utiliza o projeto Docker oficial do GeoNode e automatiza as principais etapas de preparação do ambiente:
- Instala as dependências do sistema, o Docker e o plugin Docker Compose.
- Cria um usuário dedicado para os arquivos do projeto.
- Obtém a versão selecionada do geonode-project.
- Gera a estrutura da aplicação e o .env do GeoNode.
- Cria senhas aleatórias para os serviços.
- Configura as URLs de acesso e a emissão do certificado HTTPS.
- Aplica ajustes iniciais de memória e quantidade de processos.
- Constrói as imagens e inicia os containers.
- Verifica a resposta da aplicação, o certificado e o estado dos principais serviços.
- Configura, opcionalmente, uma tarefa agendada para detectar alterações no workspace do GeoServer e atualizar as camadas no GeoNode.
- Oferece comandos para desinstalar o projeto ou realizar uma limpeza completa do Docker em uma VM de laboratório.
O pacote contém um script de entrada em Bash, o instalador em Python, um arquivo de parâmetros e as instruções de uso.
2. Antes de começar
O instalador foi preparado para uma máquina nova com Ubuntu 24.04 e arquitetura x86_64. O perfil padrão considera uma VM com aproximadamente 16 GB de RAM, com ajustes iniciais para os serviços.
Por padrão, a instalação verifica um mínimo de 14 GiB de RAM e 30 GiB livres no disco de destino. Esses limites podem ser alterados no arquivo de parâmetros, permitindo utilizar máquinas menores para testes e atividades acadêmicas. Veja os exemplos no tópico 11.
Para instalar com HTTPS, você também precisará de:
- Um domínio ou subdomínio apontando para o IP público do servidor.
- Portas TCP 80 e 443 liberadas.
- Acesso administrativo por SSH.
- Conexão com a internet para baixar os pacotes e as imagens.
O instalador prepara o software dentro da máquina. A criação do servidor, os registros de DNS e a liberação das portas devem ser feitos previamente.
Utilize uma máquina nova, sem outra aplicação ocupando as mesmas portas.
3. Baixe e descompacte o pacote
Baixe o arquivo geonode-installer-0.1.11.zip, disponibilizado junto a este post, ou acesse o repositório no GitHub, e transfira-o para o servidor. Em seguida:
unzip geonode-installer-0.1.11.zip
cd geonode-installer-0.1.11
4. Configure a instalação
Abra o arquivo de parâmetros:
nano geonode-install.env
Ele contém as seguintes opções:
GEONODE_PROJECT_REF=5.1.0
GEONODE_VERSION=5.1.0
DJANGO_BOOTSTRAP_VERSION=5.2
SYSTEM_USER=geonode
PROJECT_NAME=curso_geonode
INSTALL_DIR=/opt/geonode/curso_geonode
HOSTNAME=geonode.seudominio.com.br
ENABLE_HTTPS=true
LETSENCRYPT_EMAIL=contato@seudominio.com.br
SERVER_IPV4=
UPDATE_LAYERS_ENABLED=true
UPDATE_LAYERS_INTERVAL_HOURS=1
MIN_RAM_GB=14
MIN_DISK_GB=30
GEOSERVER_XMS=2G
GEOSERVER_XMX=4G
UWSGI_PROCESSES=4
CELERY_WORKERS=2
WAIT_SECONDS=1800
Para uma instalação semelhante à deste exemplo, os principais campos a alterar são:
| Parâmetro |
O que informar |
HOSTNAME |
Domínio, subdomínio, IP ou localhost, sem protocolo e sem barra no final. Para HTTPS, utilize um domínio.
|
LETSENCRYPT_EMAIL |
Seu endereço de e-mail. |
SERVER_IPV4 |
Opcional: IP público da VM para conferir sua
presença na resolução DNS.
|
PROJECT_NAME |
Nome do projeto, usando letras minúsculas,
números e underscore (_).
|
INSTALL_DIR |
Diretório da instalação dentro de /opt.
|
SYSTEM_USER |
Usuário que será criado para os arquivos do projeto.
|
UPDATE_LAYERS_ENABLED |
true para habilitar a atualização automática de camadas; false para desativar.
|
UPDATE_LAYERS_INTERVAL_HOURS |
Intervalo de verificação: 1, 2, 3, 4, 6, 8, 12 ou 24 horas.
|
MIN_RAM_GB |
RAM mínima aceita, em GiB. O valor 0 desativa a checagem.
|
MIN_DISK_GB |
Espaço livre mínimo no destino, em GiB. O valor 0 desativa a checagem.
|
Atenção à versão do Django: DJANGO_BOOTSTRAP_VERSION controla apenas o Django utilizado para gerar a estrutura inicial do projeto. A versão que executa dentro dos containers é determinada pelas dependências da aplicação.
Os parâmetros de versão permitem selecionar outras referências, mas isso não garante compatibilidade automática entre todas as combinações. A instalação apresentada neste post foi testada com o GeoNode 5.1.0.
5. Confira a configuração
Antes de instalar, execute:
python3 instalar.py --env geonode-install.env --check
Esse comando valida os parâmetros e consulta a resolução DNS do endereço informado, sem instalar pacotes.
Se você preencher SERVER_IPV4, ele também confere se esse IP aparece na resolução do domínio.
Essa checagem não testa a liberação das portas nem o acesso externo ao servidor.
6. Inicie a instalação
Com os parâmetros preenchidos, execute:
sudo bash instalar-geonode.sh --env geonode-install.env
Pronto! A partir desse ponto, o instalador executa as etapas automaticamente.
A primeira construção das imagens pode demorar, dependendo do processamento da máquina e da velocidade dos downloads. Mantenha a sessão SSH aberta enquanto acompanha a execução.
Embora o comando seja iniciado com sudo, o download do projeto e sua geração são executados com o usuário definido em SYSTEM_USER. As operações administrativas, como instalar pacotes e executar o Docker, continuam sob responsabilidade do root.
O usuário criado não recebe senha habilitada, acesso ao sudo ou inclusão automática no grupo Docker.
Ao final, o instalador aguarda a resposta HTTP ou HTTPS e verifica o estado dos principais serviços. Enquanto isso, informa quais componentes ainda estão pendentes. Um container aparecer como “Started” não significa que sua inicialização já terminou.
Com HTTPS desativado, o Let’s Encrypt não é exigido nessa verificação. Após a validação, o instalador configura a tarefa de atualização automática de camadas, caso ela esteja habilitada.
7. E o certificado SSL?
Com esta configuração:
ENABLE_HTTPS=true
o instalador gera as URLs HTTPS e habilita o mecanismo de emissão de certificados Let’s Encrypt incluído no projeto Docker.
Assim, não é necessário executar separadamente a instalação do Certbot no host nem copiar manualmente os certificados para o Nginx.
O domínio precisa estar apontando corretamente para o servidor, e a porta 80 deve permanecer acessível para a validação e renovação do certificado. Se houver um registro DNS IPv6, ele também precisa estar correto.
8. Posso instalar em localhost ou acessar por IP?
Sim! Para usar HTTP localmente, configure:
HOSTNAME=localhost
ENABLE_HTTPS=false
LETSENCRYPT_EMAIL=
SERVER_IPV4=
Nesse caso, a solicitação de certificado fica desativada e o endereço será:
http://localhost/
Também é possível instalar em uma VM e acessar pelo IP da rede interna. Por exemplo:
HOSTNAME=192.168.186.142
ENABLE_HTTPS=false
LETSENCRYPT_EMAIL=
SERVER_IPV4=
Nesse caso, o endereço será, por exemplo:
http://192.168.186.142/
Use um IP fixo ou uma reserva DHCP e permita o acesso à porta TCP 80 na rede.
O instalador ajusta automaticamente os cookies de sessão e CSRF: em HTTP, eles não exigem HTTPS; em HTTPS, essa exigência permanece habilitada. A proteção CSRF continua ativa nos dois modos.
Lembre-se de que localhost representa a própria máquina. Para acessar uma VM de outro computador, utilize o IP ou domínio dessa VM. Os limites de memória e disco podem ser ajustados conforme o tópico 11.
9. Como acessar pela primeira vez?
Após a conclusão, abra no navegador o domínio, IP ou endereço local configurado.
O usuário inicial é:
admin
A senha é gerada automaticamente e fica no .env da aplicação. Para consultá-la, considerando o diretório deste exemplo:
sudo awk -F= '/^ADMIN_PASSWORD=/{print $2}' \
/opt/geonode/curso_geonode/.env
Existem, portanto, dois arquivos com funções diferentes: geonode-install.env contém os parâmetros do instalador; o .env criado no diretório da aplicação contém as configurações e senhas dos serviços. Não compartilhe esse segundo arquivo.
10. Como acompanhar os serviços?
Para consultar os containers, informe explicitamente os caminhos da instalação:
sudo docker compose \
--project-directory /opt/geonode/curso_geonode \
--env-file /opt/geonode/curso_geonode/.env \
-f /opt/geonode/curso_geonode/docker-compose.yml \
ps -a
Para acompanhar o consumo de recursos:
sudo docker stats
Para consultar os logs:
sudo docker compose \
--project-directory /opt/geonode/curso_geonode \
--env-file /opt/geonode/curso_geonode/.env \
-f /opt/geonode/curso_geonode/docker-compose.yml \
logs --tail=100 django geoserver celery geonode letsencrypt
Esses comandos funcionam mesmo quando seu usuário não tem permissão para entrar na pasta do projeto. Ajuste os caminhos se tiver utilizado outro INSTALL_DIR.
Se ocorrer uma interrupção, o instalador permite tentar novamente com o mesmo arquivo de parâmetros, preservando o projeto já gerado. Ele não executa atualização automática de versão nem apaga volumes para recomeçar.
11. Como ajustar memória e disco para testes?
Os limites mínimos ficam no arquivo geonode-install.env:
MIN_RAM_GB=14
MIN_DISK_GB=30
Eles representam critérios de validação do instalador, não o consumo fixo do GeoNode. Para uma VM de testes com menos recursos, você pode reduzir esses valores e ajustar os serviços. Por exemplo:
MIN_RAM_GB=7
MIN_DISK_GB=20
GEOSERVER_XMS=512M
GEOSERVER_XMX=1G
UWSGI_PROCESSES=2
CELERY_WORKERS=1
Esse exemplo é um ponto de partida para testes, não uma garantia de capacidade para qualquer conjunto de dados. Também é possível desativar as checagens:
MIN_RAM_GB=0
MIN_DISK_GB=0
OBS: Desativar a validação não reduz o consumo dos serviços nem evita falta de memória ou disco. Configure os recursos conforme o uso previsto.
O comando –check valida o formato desses parâmetros. A comparação com a memória e o espaço disponíveis ocorre durante a instalação.
12. Como atualizar as camadas automaticamente?
Quando utilizar esta automação?
Esse recurso é útil principalmente quando você publica camadas diretamente no GeoServer, por exemplo, conectando um banco PostGIS externo, e deseja incorporá-las ou atualizar suas informações no catálogo do GeoNode.
As camadas enviadas e gerenciadas pelo próprio GeoNode já seguem seu fluxo integrado de publicação no GeoServer e não dependem dessa tarefa adicional.
A automação também não é responsável por atualizar os registros do banco: quando uma camada consulta uma tabela PostGIS, os dados são lidos pelo GeoServer diretamente dessa fonte. O updatelayers atua na integração das camadas com o catálogo do GeoNode.
O instalador incorpora essa automação baseada no procedimento apresentado no post: Atualizar camadas do GeoServer para o GeoNode automaticamente.
Para habilitar, configure:
UPDATE_LAYERS_ENABLED=true
UPDATE_LAYERS_INTERVAL_HOURS=6
Nesse exemplo, o workspace é verificado às 00h, 06h, 12h e 18h, conforme o horário do servidor. São aceitos intervalos de 1, 2, 3, 4, 6, 8, 12 ou 24 horas.
Na primeira execução, a tarefa executa updatelayers. Nas seguintes, compara um checksum dos arquivos do workspace geonode e executa o comando somente quando identifica alterações. O novo checksum é salvo apenas após uma atualização bem-sucedida, e um bloqueio evita execuções simultâneas.
Essa detecção acompanha arquivos do workspace; alterações apenas nos registros de uma tabela PostGIS não acionam a atualização.
Após a instalação, o agendamento pode ser alterado diretamente:
sudo nano /etc/cron.d/geonode-updatelayers-curso_geonode
Para consultar os registros:
sudo tail -n 100 \
/var/log/geonode-updatelayers-curso_geonode.log
Os nomes desses arquivos acompanham o PROJECT_NAME.
Se o GeoNode já estiver instalado por uma versão compatível deste instalador, você pode configurar somente essa tarefa, usando os parâmetros originais da instalação:
sudo python3 instalar.py --env geonode-install.env \
--configure-updatelayers
Esse comando não reconstrói as imagens nem reinicia a aplicação. Para remover o agendamento, configure UPDATE_LAYERS_ENABLED=false e execute novamente a mesma opção.
13. Como desinstalar e repetir a instalação?
Para facilitar os testes e atividades acadêmicas, o pacote também oferece comandos de desinstalação.
Execute a partir da pasta do instalador, fora do diretório da aplicação, utilizando o **arquivo de parâmetros original da instalação**.
Para visualizar o plano sem apagar nada:
sudo python3 instalar.py --env geonode-install.env \
--uninstall-geonode --preview
Para remover o GeoNode:
sudo python3 instalar.py --env geonode-install.env \
--uninstall-geonode
O script solicita o nome do projeto para confirmar e remove os containers, redes e volumes identificados do projeto, o diretório da aplicação e os componentes do updatelayers criados pelo instalador. A pasta pai, como /opt/geonode, também é removida se estiver vazia.
Banco de dados, camadas e arquivos enviados são apagados definitivamente, sem backup automático.
Nesse modo, o Docker, as imagens e os caches permanecem disponíveis. Por isso, uma nova instalação pode ser mais rápida.
Para solicitar também a remoção do Docker, preservando o bloqueio caso existam recursos de outros projetos:
sudo python3 instalar.py --env geonode-install.env \
--uninstall-geonode --remove-docker
Limpeza completa da VM. Em uma VM descartável e exclusiva para testes, existe uma opção mais abrangente:
sudo python3 instalar.py --env geonode-install.env \
--uninstall-geonode-completely
Será necessário digitar:
APAGAR TODO O DOCKER
Esse modo remove todos os containers, volumes, redes personalizadas, imagens e caches do Docker local, inclusive de outros projetos**, além da aplicação, dos componentes do seu updatelayers e dos pacotes Docker.
Para conferir o plano antes, acrescente –preview.
O modo completo atende à instalação Docker local padrão usada neste tutorial. Configurações como Docker remoto, armazenamento personalizado, Swarm ou namespaces de outros runtimes continuam bloqueadas.
O usuário do sistema, seu diretório pessoal e dependências gerais, como Python e Git, permanecem. Arquivos usados como bind mounts fora do diretório da aplicação também não são apagados. Portanto, essa limpeza não equivale a restaurar o sistema operacional.
Após concluir, para instalar novamente:
sudo bash instalar-geonode.sh --env geonode-install.env
14. Do servidor vazio ao GeoNode funcionando
Na instalação que motivou este post, utilizei uma máquina nova e o GeoNode 5.1.0. Ao final, o portal estava acessível pelo navegador com HTTPS funcionando.
Antes de utilizar o ambiente em um curso ou projeto, vale realizar os testes do seu fluxo: carregar camadas, abrir os dados, criar mapas e dashboards e conferir as permissões de acesso.
A automação reduz o trabalho repetitivo de preparar o ambiente. A validação com os dados e as atividades que serão utilizados continua sendo uma etapa importante.
Agora, na próxima instalação, o procedimento será bem mais curto: preencher o arquivo de configuração, executar o comando e acompanhar a criação do ambiente.
Até o próximo post!