nak0x
18064be674
- Ajout scripts/ reproduisant chaque étape (secrets, render config, up CLI, init Garage, bootstrap prod, admin, vérif E2E, adoption Coolify, backup) - Templates envsubst (config.yml, garage.toml, cantaloupe.properties) + .example - deploy.conf (config non-secrète : domaine, versions, uuids Coolify) - docs/ : ARCHITECTURE, TROUBLESHOOTING (11 problèmes/fixes), RUNBOOK, SECURITY - Makefile (raccourcis) - .gitignore + retrait du suivi de .env/.secrets.env/config.yml/garage.toml (fichiers conservés sur disque ; secrets restent dans l'historique -> voir SECURITY.md) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# Troubleshooting — problèmes rencontrés & diagnostics
|
|
|
|
Récapitulatif des 11 problèmes du déploiement (symptôme → cause → fix), + commandes de diagnostic
|
|
réutilisables. Voir aussi `README.md` §5.
|
|
|
|
---
|
|
|
|
## P1 — `manifest unknown` au pull d'une image
|
|
**Symptôme** : `docker pull …/backend:1.13.0` → `manifest unknown`.
|
|
**Cause** : `1.13.0` n'existe qu'en `-rc1` ; l'extraction du cœur numérique inventait une version.
|
|
**Fix** : n'utiliser que des **finales** (dernière = `1.12.2`). Vérifier :
|
|
```bash
|
|
tok=$(curl -s "https://gitlab.teklia.com/jwt/auth?service=container_registry&scope=repository:arkindex/backend:pull" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
|
|
curl -s -H "Authorization: Bearer $tok" https://registry.gitlab.teklia.com/v2/arkindex/backend/tags/list \
|
|
| tr ',' '\n' | grep -oE '"[0-9]+\.[0-9]+\.[0-9]+"' | tr -d '"' | sort -uV | tail
|
|
```
|
|
|
|
## P2 — Pas de certificat wildcard possible
|
|
**Cause** : Coolify = challenge HTTP-01 seulement.
|
|
**Fix** : énumérer chaque hostname dans les règles `Host(...)` (Garage, Cantaloupe). Diag certs :
|
|
```bash
|
|
for h in ark s3.ark staging.s3.ark uploads.iiif.ark; do
|
|
curl -sS -o /dev/null -w "$h.nak0x.dev -> %{http_code} tls=%{ssl_verify_result}\n" "https://$h.nak0x.dev/"
|
|
done # tls=0 = certificat valide
|
|
```
|
|
|
|
## P3 — `PermissionError: /arkindex.yml`
|
|
**Cause** : fichiers montés en `600` (uid 1000), backend en uid **2000**.
|
|
**Fix** : `chmod 644 config.yml garage.toml cantaloupe.properties` (fait par `scripts/01`).
|
|
|
|
## P4 — Worker : `redis AuthenticationError` ⭐
|
|
**Symptôme** : « HELLO must be called with the client already authenticated ».
|
|
**Cause** : sur le réseau `coolify`, le nom générique `redis` résout vers **`coolify-redis`**
|
|
(protégé par mot de passe), pas le nôtre.
|
|
**Diagnostic** :
|
|
```bash
|
|
docker exec ark-worker-<suffix> getent hosts redis # IP de coolify-redis (mauvais)
|
|
docker exec ark-worker-<suffix> getent hosts ark-redis # IP correcte
|
|
```
|
|
**Fix** : référencer les services par leur **nom unique** `ark-redis`/`ark-database`/`ark-solr`/
|
|
`ark-garage` (jamais `redis`/`db`). Appliqué dans `config.yml` et `cantaloupe.properties`.
|
|
|
|
## P5 — `bootstrap` refuse en prod
|
|
**Cause** : `You cannot run this script in production.` + URLs `*.ark.localhost` codées en dur.
|
|
**Fix** : réplique manuelle → `scripts/20-garage-init.sh` + `scripts/30-arkindex-init.sh`.
|
|
|
|
## P6 — S3 en virtual-host (et non path-style)
|
|
**Cause** : backend force `addressing_style="auto"` (boto3) → `<bucket>.s3.<DOMAIN>`.
|
|
**Fix** : énumérer les 9 sous-domaines de bucket + `root_domain` dans `garage.toml`.
|
|
**Test** :
|
|
```bash
|
|
docker exec -i ark-backend-<suffix> arkindex shell <<'PY'
|
|
from arkindex.project.aws import s3
|
|
o=s3.Bucket("staging").Object("t"); o.put(Body=b"x"); print(o.get()["Body"].read()); o.delete()
|
|
PY
|
|
```
|
|
|
|
## P7 — Trop de workers gunicorn
|
|
**Cause** : `nproc*2+1` = 9.
|
|
**Fix** : `MAX_WORKERS: "3"` dans l'env du backend.
|
|
|
|
## P8 — Statics admin/swagger non stylés
|
|
**Cause** : pas de WhiteNoise ; statics servis par CDN.
|
|
**Fix** : `static.cdn_assets_url: https://assets.teklia.com/arkindex`. Cosmétique (API/SPA OK).
|
|
|
|
## P9 — `reindex --setup` demande un corpus
|
|
**Cause** : collections Solr créées **par corpus** à la volée. Rien à pré-créer.
|
|
|
|
## P10 — Backend sans Pillow (tests)
|
|
**Cause** : traitement image côté workers. Pour un test : générer le JPEG hors backend +
|
|
uploader via un conteneur `amazon/aws-cli` (cf. `scripts/50-verify.sh`).
|
|
|
|
## P11 — Adoption Coolify : volumes vidés + container_name écrasé
|
|
**Causes** :
|
|
1. Coolify **remappe** les volumes nommés en `<uuid>_*` et **ignore `external:`** → volumes vides.
|
|
2. Coolify écrase `container_name` en `<service>-<uuid>` (mais garde le **nom de service** = alias DNS).
|
|
**Fix** :
|
|
1. Sur un déploiement neuf : ré-init (`scripts/20/30/40`) contre les conteneurs Coolify. Pour des
|
|
données existantes : utiliser des **bind-mounts absolus** (dossiers hôte) au lieu de volumes nommés.
|
|
2. Nommer les **services** `ark-*` (déjà unique → pas de collision P4).
|
|
**Piège** : ne déclencher le deploy **qu'une fois** (POST *ou* GET `/api/v1/deploy?uuid=`).
|
|
|
|
---
|
|
|
|
## Diagnostics rapides
|
|
```bash
|
|
# logs d'un service
|
|
docker logs --tail 50 ark-backend-<suffix>
|
|
# résolution DNS depuis un conteneur
|
|
docker exec ark-worker-<suffix> getent hosts ark-redis
|
|
# état santé
|
|
docker inspect ark-backend-<suffix> --format '{{.State.Health.Status}}'
|
|
# mémoire par conteneur
|
|
docker stats --no-stream --format 'table {{.Name}}\t{{.MemUsage}}' | grep ark-
|
|
# routers Traefik vus par le proxy
|
|
docker exec coolify-proxy wget -qO- http://localhost:8080/api/http/routers 2>/dev/null | head
|
|
```
|