# 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
```