Standalone-Arkindex-Coolify/docs/TROUBLESHOOTING.md

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 :

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 :

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 :

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 :

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 :
3. 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.
4. 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

# 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