Quando um carro se recusa a partir, um bom mecânico não troca o motor: ele olha o painel (qual luz está acesa?), ele escuta (qual barulho, em que momento?), e só em último recurso ele zera tudo. O laboratório se conserta do mesmo jeito. Gesto 1, etat: o painel, quem está rodando, quem responde. Gesto 2, journal <serviço>: o barulho, as cem últimas linhas do que o serviço conta, onde quase sempre se encontra a frase que explica tudo. Gesto 3, reinitialiser: a volta ao zero, que apaga contêineres e dados e lhe devolve um laboratório novo em dois minutos. Entre o gesto 2 e o gesto 3, esta lição lhe dá um catálogo de doze falhas vistas e revistas, cada uma com sua mensagem exata, sua causa e seu remédio. Nove vezes em dez, você não chegará ao gesto 3.
O que cada gesto lhe diz:
| Gesto | Comando | O que você lê | Quanto tempo |
|---|---|---|---|
| 1 | ./labo.sh etat · .\labo.ps1 etat | coluna STATUS: Up … (healthy), Up … (unhealthy), Exited (137), ou contêiner ausente; depois ✔/✘ por serviço e os contadores | 10 s |
| 2 | ./labo.sh journal elasticsearch (ou kibana, neo4j, opensearch) | 100 últimas linhas; procure ERROR, FATAL, bootstrap check, Exception | 1 min |
| 3 | ./labo.sh reinitialiser depois demarrer, importer, charger-graphe | pede confirmação (oui); remove contêineres e volumes | 3 min |
O gesto 3 só toca nos contêineres labo-* e nos três volumes labo-recherche-graphes_es-data, _neo4j-data, _os-data. Você perde o que criou por conta própria (índices de sandbox, painéis, nós de teste); os dados do curso são recarregados com importer e charger-graphe.
Um log saudável, para reconhecer em seguida um log doente (três linhas reais coletadas com journal):
labo-elasticsearch | {"@timestamp":"2026-09-09T13:39:45.630Z","log.level": "INFO", "current.health":"GREEN","message":"Cluster health status changed from [YELLOW] to [GREEN] (reason: [shards started [[cours][0]]])." …}
labo-kibana | [2026-09-09T13:37:16.402+00:00][INFO ][status] Kibana is now available
labo-neo4j | 2026-09-09 13:38:32.401+0000 INFO Started.O Elasticsearch fala em JSON (uma linha por evento, campo message), o Kibana em colchetes [data][NÍVEL][módulo], o Neo4j em texto. As três frases acima são as que queremos ver. O Kibana também emite WARN sem gravidade (Error initializing AI assistant resources: Platinum, Enterprise or trial license needed, Error while trying to load prerelease flag): ignore-os.
As doze falhas, por ordem de frequência em sala de aula. As mensagens marcadas "coletada" foram reproduzidas no laboratório do curso; as outras são citadas tal como os motores as emitem.
Porta já em uso (coletada). demarrer falha imediatamente com:
Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint labo-elasticsearch (…): Bind for 0.0.0.0:9200 failed: port is already allocatedCausa: outro programa já escuta na 9200 (um Elasticsearch instalado "direto" na máquina, outro projeto Docker), ou na 5601, 7474, 7687. Remédio: prerequis lhe diz qual porta; encontre o culpado (Get-NetTCPConnection -LocalPort 9200 no PowerShell, sudo ss -ltnp | grep 9200 no Linux/macOS), pare-o ou, se precisar mantê-lo, mude a porta do lado do host no docker-compose.yml ("9202:9200") e adapte os endereços do curso.
Contêiner Exited (137). etat exibe labo-elasticsearch Exited (137) 2 minutes ago, e o log para de repente sem mensagem de erro. Causa: código 137 = morto pelo sinal 9, quase sempre o OOM killer: o Docker não tem memória suficiente para três JVMs (Elasticsearch e Neo4j reclamam até 1 GB de heap cada, mais o Kibana). docker inspect labo-elasticsearch --format '{{.State.OOMKilled}}' responde true. Remédio: lição 02, etapa 1 ou 2: aumente a memória do Docker para 6 GB (.wslconfig depois wsl --shutdown no Windows), depois demarrer. Não ative o perfil OpenSearch abaixo de 6 GB.
Linux: vm.max_map_count muito baixo. O Elasticsearch (ou o OpenSearch) sai em alguns segundos e seu log termina com:
bootstrap check failure [1] of [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
ERROR: Elasticsearch did not exit normally - check the logs at /usr/share/elasticsearch/logs/labo.logCausa: limite do kernel Linux do host, que o contêiner não pode mudar por conta própria. Remédio: sudo sysctl -w vm.max_map_count=262144, torne-o permanente em /etc/sysctl.conf (lição 02, etapa 3), depois demarrer. No Docker Desktop (Windows, macOS), o valor já é 262144.
"Kibana server is not ready yet". A página http://localhost:5601 exibe apenas essa frase. Causa: o Kibana aguarda o Elasticsearch. Ou é cedo demais (os 40 primeiros segundos), ou o Elasticsearch caiu (falha 2 ou 3), e journal kibana repete Unable to retrieve version information from Elasticsearch nodes. connect ECONNREFUSED 172.x.x.x:9200. Remédio: etat. Se o Elasticsearch estiver healthy, aguarde um minuto e recarregue; senão, repare o Elasticsearch primeiro, o Kibana seguirá sozinho (restart: unless-stopped).
Disco quase cheio: índices em somente leitura. Com 95% do disco cheio, um Elasticsearch padrão registra flood stage disk watermark [95%] exceeded on […] all indices on this node will be marked read-only e toda escrita responde 429: cluster_block_exception … blocked by: [TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark, index has read-only-allow-delete block]. No laboratório, você não verá essa mensagem: o compose fixa cluster.routing.allocation.disk.threshold_enabled=false (verificável com GET _nodes/settings?filter_path=nodes.*.settings.cluster.routing). O risco restante é no space left on device no log durante importer. Remédio: docker system df para medir, docker image prune para liberar, depois reexecute importer.
O Neo4j recusa a senha (coletada). No Neo4j Browser: Connection to instance failed — The client is unauthorized due to authentication failure. (detalhes: Neo.ClientError.Security.Unauthorized). No etat: ✘ Neo4j ne répond pas (Neo4j não responde), e na linha de comando o cypher-shell diz The client is unauthorized due to authentication failure. Causa A: erro de digitação, a senha é aiopsatlas2026. Causa B, mais traiçoeira: o volume neo4j-data foi criado em uma inicialização anterior com outra senha; NEO4J_AUTH só se aplica na primeiríssima inicialização, e o log diz isso preto no branco (linha coletada): Changed password for user 'neo4j'. IMPORTANT: this change will only take effect if performed before the database is started for the first time. Remédio A: digite novamente. Remédio B: reinitialiser depois demarrer e charger-graphe.
Conflito de nome de contêiner (coletada). demarrer falha com:
Error response from daemon: Conflict. The container name "/labo-elasticsearch" is already in use by container "a26fe0358d63…". You have to remove (or rename) that container to be able to reuse that name.Causa: um contêiner labo-elasticsearch já existe mas não pertence a este projeto Compose, tipicamente porque você clonou o kit em uma segunda pasta, ou executou um docker run --name labo-elasticsearch à mão. Remédio: docker rm -f labo-elasticsearch (somente o contêiner, os dados do volume permanecem), depois demarrer. Se o conflito envolver os cinco nomes, docker rm -f $(docker ps -aq --filter name=labo-).
O Git Bash reescreve os caminhos /labo (coletada). No Windows, no Git Bash, um comando digitado à mão como docker compose exec -T neo4j ls /labo/cypher responde:
ls: cannot access 'C:/Program Files/Git/labo/cypher': No such file or directoryCausa: a emulação MSYS do Git Bash converte todo argumento que começa com / em caminho Windows antes de passá-lo ao docker. Remédio: labo.sh exporta MSYS_NO_PATHCONV=1 e MSYS2_ARG_CONV_EXCL='*' desde sua segunda linha, portanto todos os comandos do script estão protegidos. Para seus próprios comandos no Git Bash, prefixe-os: MSYS_NO_PATHCONV=1 docker compose exec -T neo4j ls /labo/cypher (coletado: a lista dos arquivos .cypher aparece).
PowerShell 5.1 e Invoke-RestMethod quebram os acentos (coletada). Você envia uma consulta com uma palavra acentuada a partir do PowerShell:
$corps = '{"analyzer":"french","text":"déployés en production"}'
Invoke-RestMethod -Uri http://localhost:9200/cours/_analyze -Method Post -ContentType 'application/json' -Body $corpsO PowerShell 5.1 responde Le serveur distant a retourné une erreur : (400) Demande incorrecte. (O servidor remoto retornou um erro: (400) Solicitação incorreta); do lado do Elasticsearch a razão é x_content_parse_exception … Invalid UTF-8 middle byte 0x70. Causa: o PowerShell 5.1 codifica o corpo em Latin-1 enquanto o Elasticsearch espera UTF-8; o mesmo comando no PowerShell 7 funciona. Remédio: passe pelo Kibana Dev Tools para todas as consultas do curso (UTF-8 garantido); o próprio labo.ps1 usa curl dentro dos contêineres. Para criar scripts mesmo assim: PowerShell 7, ou -Body ([System.Text.Encoding]::UTF8.GetBytes($corps)).
O Docker Desktop não está iniciado. Todo comando docker (portanto prerequis, etat, demarrer) falha com:
error during connect: Get "http://%2F%2F.%2Fpipe%2FdockerDesktopLinuxEngine/v1.51/info": open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.(Cannot connect to the Docker daemon at unix:///var/run/docker.sock no macOS/Linux.) prerequis traduz: ✘ le démon Docker ne répond pas — lancez Docker Desktop et attendez l'icône verte (o daemon Docker não responde — abra o Docker Desktop e aguarde o ícone verde). Causa: Docker Desktop fechado, ou ainda iniciando após uma sessão do Windows. Remédio: abra o Docker Desktop, aguarde até que o ícone pare de se animar, reexecute o comando. Os contêineres em restart: unless-stopped voltam por conta própria.
Download muito lento ou TLS handshake timeout. Durante == Téléchargement des images ==:
Error response from daemon: Get "https://registry-1.docker.io/v2/": net/http: TLS handshake timeoutou failed to copy: read tcp … connection reset by peer. Causa: rede saturada, wi-fi de escola, proxy corporativo; as imagens pesam 2,5 a 2,8 GB cada. Remédio: nada a reparar, reexecute demarrer: o Docker retoma as camadas já baixadas (Already exists). Atrás de um proxy, configure-o em Docker Desktop → Settings → Resources → Proxies.
Volume cheio ou dados corrompidos: a volta ao zero. Sintomas variados: etat exibe o cluster em red, o log do Elasticsearch fala de CorruptIndexException ou de no space left on device, o Neo4j fica travado em recovery após um desligamento brutal do PC, ou mais simplesmente nada mais faz sentido após uma manipulação arriscada. Remédio, o gesto 3:
./labo.sh reinitialiser # répondre : oui
./labo.sh demarrer
./labo.sh importer
./labo.sh charger-graphe.\labo.ps1 reinitialiser
.\labo.ps1 demarrer
.\labo.ps1 importer
.\labo.ps1 charger-grapheO que é preciso ver: reinitialiser executa docker compose --profile opensearch down -v --remove-orphans e confirma ✔ labo remis à zéro (laboratório zerado). As imagens permanecem em cache: nenhum novo download, e o trio seguinte leva dois a três minutos. O que é preciso saber: arreter (sem -v) conserva os dados; reinitialiser os apaga, é a única diferença.
etat não lista nenhum contêiner e demarrer recria tudo a cada vez → Você executa o script a partir de uma segunda cópia do repositório. Mantenha uma única cópia do kit e execute sempre os comandos a partir da sua raiz.
journal exibe milhares de linhas JSON ilegíveis → Normal para o Elasticsearch. Filtre pelas palavras-chave: no PowerShell .\labo.ps1 journal elasticsearch | Select-String 'ERROR|WARN|bootstrap', no bash ./labo.sh journal elasticsearch | grep -E 'ERROR|WARN|bootstrap'.
Após reinitialiser, o Kibana exibe novamente «Vos données ne sont pas sécurisées» (Seus dados não estão protegidos) → Banner normal de um Kibana sem segurança; ele volta porque a configuração do Kibana foi apagada com o volume. Clique em «Rejeter» (Descartar).
etat (o que não vai bem), journal <serviço> (por quê), reinitialiser (último recurso, apaga os dados do laboratório mas não as imagens).Exited (137) = memória; port is already allocated = porta ocupada; vm.max_map_count [65530] is too low = Linux a ajustar; Neo.ClientError.Security.Unauthorized = senha; container name … already in use = docker rm.labo.sh neutraliza a conversão de caminhos do Git Bash.Invoke-RestMethod no PowerShell 5.1: o Dev Tools e o labo.ps1 cuidam disso corretamente.arreter guarda os dados, reinitialiser os apaga. Os dados do curso são sempre recarregados em dois comandos.docker inspect --format '{{.State.Health.Status}}' labo-elasticsearch retorna starting, healthy ou unhealthy: é exatamente o que demarrer lê a cada três segundos. {{json .State.Health.Log}} mostra os cinco últimos resultados do healthcheck.