dsp-core¶

Este módulo é parte do DSP — veja a documentação completa em dsp-docs. As informações abaixo tratam apenas deste módulo.

Objetivo¶

O dsp-core é o hub de orquestração Docker Compose do DSP. Ele não contém código de aplicação/domínio — sua responsabilidade é preparar e subir a infraestrutura (bancos, GeoServers, gateway, jobs de migração e geo-file) e orquestrar o build dos demais módulos.

flowchart TD
  core["dsp-core"]
  be["dsp-backend"]
  fe["dsp-frontend"]
  job["dsp-job-data-migration"]
  geoFile["dsp-job-geo-file-generation"]
  storage["dsp-object-storage (SeaweedFS)"]
  gs["2 GeoServers + 2 bancos Postgres/PostGIS"]
  gw["dsp-gateway"]

  core --> be
  core --> fe
  core --> job
  core --> geoFile
  core --> storage
  core --> gs
  core --> gw

Responsabilidades¶

• Configuração de exemplo do adotante.
• Conteúdo de exemplo da página About (config/about/).
• SQL de inicialização dos bancos.
• GeoServer Exhibition (mapa) e GeoServer Download (WFS de exportação).
• Gateway nginx (dsp-gateway) como porta de entrada única da stack.
• Object storage SeaweedFS (dsp-object-storage, profile object-storage) e job geo-file (dsp-job-geo-file-generation, mesmo profile) — obrigatórios no adotante real; a Demo Brasil não sobe esses serviços.
• Job de migração (dsp-job-migration, profile migration).
• Três scripts operacionais: ./config.sh, ./setup.sh, ./start.sh.
• Clone automático dos repositórios irmãos quando ausentes (com preview da estrutura de pastas antes da confirmação). O script olha a pasta curta (backend e equivalentes) e, se o código não estiver lá, a pasta com o nome do repositório (dsp-*). Se as duas faltarem, o download cria a pasta dsp-*. ./config.sh também clona o job se faltar.

Pré-requisitos¶

Os três scripts¶

./config.sh¶

Wizard interativo que grava config/adopter/adopter-config.yaml e, na reaplicação, gera os arquivos operacionais (lista abaixo). Entrada: ./config.sh (sem argumentos).

• config/installation/installation-config.json — hierarquia, telas, KPIs, map.initialView, painel de detalhe da AOI.
• config/map/mapLayersConfig.json — grupos e camadas WMS, SRIDs.
• config/downloads/downloadThemesConfig.json — temas da tela Downloads.
• config/about/about-config.json — índice da página About (quando habilitada); Markdown em config/about/.
• config/Job-Data-Migration/application/application.yaml — datasources e mapeamento ETL.
• config/Job-Geo-File-Generation/application/application.yaml — object storage (SeaweedFS); sem cron no YAML.
• .env — DSP_SOURCE_*, DSP_OBJECT_STORAGE_* e demais chaves que o wizard preenche.

Esses artefatos operacionais não devem ser editados manualmente — são derivados e regenerados a cada reaplicação de ./config.sh. Ajuste sempre config/adopter/adopter-config.yaml (wizard ou editor) e depois reaplique.

Rodar sem argumentos (./config.sh). Antes do wizard, o script procura cada módulo na pasta curta (backend, frontend, job-data-migration, job-geo-file-generation) e, se o código não estiver lá, na pasta dsp-*. Se as duas faltarem, oferece clonar para a pasta com o nome do repositório.

O wizard não pergunta horário de job batch nem grava DSP_MIGRATION_CRON ou DSP_GEO_FILE_GENERATION_CRON. Reaplicar (opção 1) não altera crons no .env.

Primeira execução (sem adopter-config.yaml ainda): o script pergunta como configurar:

Execuções seguintes (quando o YAML já existe):

O wizard é dividido em 6 etapas. Em cada uma, o operador responde perguntas guiadas (com explicação do campo e do impacto) até cobrir a configuração necessária e a personalização do adotante:

No terminal o wizard mostra 5 estágios numerados (1–5) mais o bloco About opcional ao final — na documentação, o About conta como 6ª etapa.

Object storage (SeaweedFS) não é perguntado no wizard. Credenciais e endpoint ficam em environment.object_storage no adopter-config.yaml (veja adopter-config.yaml.example); o ./config.sh copia isso para DSP_OBJECT_STORAGE_* no .env na reaplicação. A agenda do job geo-file (DSP_GEO_FILE_GENERATION_CRON) vem do ./setup.sh, não desta etapa.

O ./config.sh (opção 2 — editar) reabre esse mesmo wizard de 6 etapas com os valores atuais preenchidos.

Jobs gerados automaticamente¶

O wizard não pergunta quais jobs fixos ligar. O application.yaml gerado habilita sempre L1, L2, L3, área de interesse e kpi-job. A flag layer-jobs fica true quando há entradas em etl.layers[]; caso contrário, false.

A área exibida nos KPIs não vem da origem: o kpiCalculationJob calcula dsp.area_of_interest.area e grava temas em dsp.kpi_measure depois da migração. A etapa 5 define theme_count (0–4), a layer de cada tema, a unidade de área e as cores. Detalhe: Cálculo de KPIs.

SQL avançado em source_table (níveis fixos)¶

No wizard, source_table deve ser schema.tabela. Para subconsultas SQL (JOINs, aliases), edite diretamente o adopter-config.yaml com bloco YAML dobrado (>-), conforme o exemplo em adopter-config.yaml.example. Os nomes das colunas abaixo devem bater com os aliases do SELECT. Depois, ./config.sh → Reaplicar.

Camadas genéricas unificadas (etl.layers[])¶

Cada item alimenta três destinos a partir de uma única configuração:

A mesma source_table pode aparecer mais de uma vez se layer_name (e portanto a tabela destino dsp.<nome>) for distinto. Ao adicionar outra camada com a mesma origem no wizard, os campos de estrutura (PK, FK, geometria, datas, SRID) são reutilizados como padrão.

Para não migrar ou exibir uma camada, remova-a de etl.layers[] e reaplique — não use enabled: false no YAML do adotante.

Na etapa 6/6, o adotante pode recusar a página About; nesse caso ela permanece desabilitada. Se habilitar, o wizard valida extensão e existência dos arquivos Markdown e gera ids de aba (tab-1, tab-2, …) em about-config.json.

Página About (config/about/)¶

A pasta config/about/ traz o conteúdo de exemplo da página About do frontend: about-config.json.example (índice de exemplo) e os Markdown de demonstração (*.quickstart.md.example, copiados no modo Demonstração). O fluxo normal do wizard é informar um Markdown de qualquer pasta do computador, que é copiado para config/about/.

O YAML do adotante (config/adopter/adopter-config.yaml / .yaml.example) tem uma seção about com os campos:

apply_config() gera config/about/about-config.json com ids automáticos (tab-1, tab-2, …) a partir da ordem das abas. O backend lê esses arquivos em /config/about/ dentro da imagem (copiados no build). Variáveis: DSP_ABOUT_CONFIG_FILE e DSP_ABOUT_CONTENT_DIR (.env.example).

./setup.sh¶

Prepara bancos, GeoServer e (no fluxo real) a primeira migração. Roda sem argumentos e apresenta um menu com três opções:

Submenu da opção 2 — plano de migração¶

1. Quando deve rodar a carga inicial?

2. Como a migração deve se comportar depois?

No modo Continuous, o script pergunta How often should the data be synchronized after the initial migration?: todo dia num horário; a cada N horas; ou a cada N minutos (1–59, útil para teste local). O horário de Schedule for later é reutilizado se a escolha for “todo dia”.

Em seguida (ainda no step 3 do setup, opção 2), pergunta o cron de pré-geração de arquivos de download — expressão Unix de 5 campos para DSP_GEO_FILE_GENERATION_CRON (padrão: valor atual do .env ou 0 2 * * *). Deve ficar numa janela depois da migração periódica, quando houver DSP_MIGRATION_CRON. O adotante não digita a expressão de migração manualmente; para pré-geração, informa o cron diretamente ou aceita o padrão com Enter.

Valores de migração e pré-geração são gravados no .env no fim do setup (step 9), junto com DSP_MIGRATION_*. Reexecutar ./setup.sh (adotante real) repete as perguntas, usando o .env como padrão.

Fuso da migração: DSP_MIGRATION_TZ no .env (veja .env.example). Pré-geração herda DSP_MIGRATION_TZ quando DSP_GEO_FILE_GENERATION_TZ está vazio.

Se config/Job-Data-Migration/application/application.yaml ainda for idêntico ao template (.example), o setup.sh interrompe com erro — rode ./config.sh ou edite o arquivo antes.

Bancos e publicação de camadas¶

Antes de migrar, o script espera a inicialização completa do PostgreSQL (pg_isready + schemas dsp e data_migration criados pelo SQL de init).

AOI e camadas genéricas só existem nos GeoServers depois que o job populou o geoserver-db.

./start.sh¶

Use depois do ./setup.sh. Não roda migração, seed, populate de GeoServer nem sobe bancos/jobs — apenas rebuilda e liga dsp-backend, dsp-frontend e dsp-gateway (com docker compose … --no-deps, para não religar a infra via depends_on).

Camadas no mapa e primeira carga de dados continuam sendo responsabilidade do ./setup.sh (ou do job agendado depois). Se você fez docker compose down sem -v, o ./start.sh não religa bancos nem GeoServers — siga o comando que o script imprime no erro ou rode ./setup.sh de novo.

Bancos e GeoServer¶

Só os bancos publicam porta no host. Os serviços HTTP ficam acessíveis apenas pelo gateway. Os dois jobs não expõem HTTP — sobem por profile do Compose.

Fluxo dual-write¶

flowchart LR
  src[(Fonte JDBC do adotante)] --> job[Job de migração]
  job -->|"negócio + bbox/centroid"| dspdb[(dsp-db)]
  job -->|"geometria completa"| exdb[(dsp-geoserver-db)]
  exdb --> gsEx[GeoServer Exhibition WMS]
  exdb --> gsDl[GeoServer Download WFS]
  exdb --> geoFile[Job geo-file]
  geoFile -->|CSV pré-gerado| s3[(dsp-object-storage SeaweedFS)]
  dspdb --> be[Backend serve API]
  be --> fe[Frontend consome API + WMS]
  be -->|WFS downloads| gsDl
  be -->|CSV S3-first| s3

Gateway (dsp-gateway)¶

Container nginx que é a porta de entrada única da stack. Frontend, backend e os dois GeoServers não publicam porta no host — tudo entra por DSP_GATEWAY_HOST_PORT (default 8026).

A configuração fica em config/Gateway/nginx/default.conf.template, é copiada para a imagem no docker compose build (/etc/nginx/templates/) e processada por envsubst quando o container sobe, substituindo apenas as variáveis DSP_*. O volume dsp_gateway_cache guarda só o cache, não os templates.

Os dois GeoServers respondem em /geoserver internamente, então cada um recebe um prefixo externo próprio e um rewrite. Cada um também recebe PROXY_BASE_URL com a sua URL pública, para que os links do GetCapabilities e da interface web saiam corretos.

Como o gateway resolve os upstreams em runtime pelo DNS do Docker, ele sobe mesmo com algum serviço parado — responde 502 em vez de falhar no boot. Isso é o que permite usar o modo demo do ./setup.sh, que não sobe backend nem frontend.

Cache¶

O cache já está configurado, mas vem desligado. Ele cobre apenas os endpoints WMS/WFS (/geoserver-exhibition/<workspace>/wms, /wfs e os equivalentes em /geoserver-download/), que não têm sessão — a UI web e a REST do GeoServer ficam de fora para não quebrar o login do admin.

Para ligar, deixe DSP_GATEWAY_CACHE_BYPASS vazio no .env e recrie o container:

# .env
DSP_GATEWAY_CACHE_BYPASS=
DSP_GATEWAY_CACHE_TTL=10m

docker compose --env-file .env up -d --force-recreate dsp-gateway

O header X-Cache-Status (HIT, MISS, BYPASS) sai em toda resposta dos GeoServers e serve para conferir o comportamento. Para limpar o cache, remova o volume dsp_gateway_cache.

URLs padrão¶

Variáveis de ambiente relevantes (.env do core)¶

O .env é criado automaticamente na primeira execução de ./config.sh, ./setup.sh ou ./start.sh (a partir de .env.example). Não é necessário copiá-lo manualmente.

O ./config.sh grava JDBC, SRID e DSP_OBJECT_STORAGE_* (a partir de environment no adopter YAML) no .env. As agendas de migração e geo-file vêm do ./setup.sh (adotante real). Compreender as variáveis abaixo ajuda a personalizar a instalação e a solucionar problemas.

Veja também: Instalação completa, Bancos de dados.

Estrutura de configuração gerada¶

config/adopter/adopter-config.yaml é o arquivo central produzido pelo wizard ./config.sh. A partir dele são derivados os arquivos operacionais consumidos por backend (installationConfig.json, mapLayersConfig.json, downloadThemesConfig.json, about-config.json) e pelo job de migração (application.yaml), evitando que cada módulo precise ser configurado manualmente e de forma isolada.

O wizard ./config.sh produz um único adopter-config.yaml e, a partir dele, deriva todos os artefatos operacionais consumidos pelos demais módulos. O downloadThemesConfig.json entra nesse pipeline como catálogo de temas para a tela de Downloads e para o proxy WFS do backend. O about-config.json entra nesse pipeline como índice de conteúdo (banner + abas) da página About do frontend.

flowchart LR
  configSh["./config.sh"]
  configSh --> installJson["installation-config.json"]
  configSh --> mapJson["mapLayersConfig.json"]
  configSh --> downloadJson["downloadThemesConfig.json"]
  configSh --> aboutJson["about-config.json"]
  configSh --> appYaml["Job-Data-Migration application.yaml"]
  configSh --> geoYaml["Job-Geo-File-Generation application.yaml"]
  configSh --> dotenvStorage[".env DSP_OBJECT_STORAGE_* / DSP_SOURCE_*"]
  installJson --> build["docker compose build<br/>contexto dsp_config"]
  mapJson --> build
  downloadJson --> build
  aboutJson --> build
  appYaml --> build
  geoYaml --> build
  dotenvStorage --> setupSh["./setup.sh grava crons no .env"]
  build --> backendImg["dsp-backend /config"]
  build --> geoserverImg["GeoServers /config"]
  build --> jobImg["dsp-job-migration /config"]

• ./config.sh — ponto de entrada do adotante; wizard, reaplicação ou recriação do adopter-config.yaml e geração dos JSON/YAML operacionais listados acima.
• select-runtime-config.sh — no build Docker, escolhe o arquivo ativo ou o .example e copia para /config dentro da imagem.
• installation-config.json — labels, hierarquia, telas, KPIs e screens.home.detail.fields (DSP_INSTALLATION_CONFIG_FILE). Esse array não vai para o application.yaml do job.
• mapLayersConfig.json — grupos e camadas WMS; publicadas nos GeoServers pelo populate_geoserver.sh.
• downloadThemesConfig.json — temas de download (AOI + etl.layers[]); formats é csv e gpkg; wfsBaseUrl em ${DSP_PUBLIC_BASE_URL}/geoserver-download/dsp/wfs.
• about-config.json — índice About (enabled, bannerTitle, tabs com ids tab-1, tab-2, …).
• application.yaml — plano ETL. Copiado para a imagem do job no build (com entrypoint e scripts de publicação GeoServer).
• config/Job-Geo-File-Generation/application/application.yaml — S3 do job de pré-geração (sem cron; agenda só no .env via ./setup.sh).
• Imagens dsp-backend, GeoServers, dsp-job-migration, bancos e dsp-gateway — configs e SQL de init copiados no build via dsp_config; volumes guardam só dados (e cache do gateway).
• Imagem dsp-object-storage — SeaweedFS (weed mini) com credenciais em s3.json na imagem. Volume dsp_object_storage_data guarda os objetos; tamanho e quantidade de volumes internos são calculados pelo weed mini conforme o espaço livre no volume Docker.

Veja também: Fluxo de dados (runtime) e dsp-backend (variáveis de ambiente de downloads).