Standalone-Arkindex-Coolify/README.md

# Déploiement Arkindex sur Coolify — Guide & Runbook

Déploiement d'**Arkindex** (plateforme Teklia d'analyse de documents, édition Community/AGPL) en
**un seul projet** sur un serveur **Coolify**, exposé via le proxy Traefik de Coolify.

- **Serveur** : VPS Contabo, IP publique `167.86.101.155`, Docker 29, Coolify 4.1.2, `coolify-proxy` = Traefik v3.6.
- **Domaine** : `ark.nak0x.dev` (wildcard DNS `*.nak0x.dev` déjà en place → aucune modif DNS).
- **Date** : 2026-07-09.
- **Dossier** : `~/arkindex-deploy/`.

> ⚠️ Les secrets ne figurent PAS dans le dépôt. Ils sont dans `.secrets.env` (git-ignoré, généré
> aléatoirement) et injectés dans `.env`, `config.yml`, `garage.toml`. Voir `docs/SECURITY.md`.

## Démarrage rapide
```bash
make secrets        # génère .secrets.env
make config         # rend config.yml / garage.toml / cantaloupe.properties / .env
make deploy-cli     # déploiement complet en docker compose (CLI)
make verify         # vérification end-to-end
# adoption dans l'UI Coolify :
make coolify-adopt  # crée la ressource, puis suivre les instructions affichées
make help           # toutes les cibles
```
Adapter d'abord le domaine et les versions dans **`deploy.conf`**.

## Structure du dépôt
```
README.md                     ce guide (architecture, procédure, problèmes/fixes)
deploy.conf                   config NON-secrète (domaine, versions, uuids Coolify)
docker-compose.yml            stack CLI (docker compose)
docker-compose.coolify.yml    variante adoptée par Coolify (services ark-*, volumes external)
config.yml / garage.toml /    fichiers de conf RÉELS (git-ignorés — contiennent des secrets ;
  cantaloupe.properties         montés par la stack en cours)
templates/*.tmpl              templates rendus par scripts/01 (envsubst)
scripts/                      00-gen-secrets, 01-render-config, 10-up-cli, 20-garage-init,
                              30-arkindex-init, 40-create-admin, 50-verify, 90-coolify-adopt,
                              99-backup-db, lib.sh
docs/                         ARCHITECTURE.md, TROUBLESHOOTING.md, RUNBOOK.md, SECURITY.md
Makefile                      raccourcis
```

---

## 1. Architecture

Stack de 8 conteneurs, réseau interne `ark`, + réseau `coolify` (externe) pour les 4 services exposés.
Le **Traefik interne d'Arkindex a été supprimé** : routage + TLS délégués au `coolify-proxy` via labels.

| Service (conteneur) | Image | Exposé sur | Rôle |
|---|---|---|---|
| `ark-database` | postgis/postgis:17-3.5 | interne | PostgreSQL + PostGIS |
| `ark-redis` | redis:alpine | interne | broker RQ + cache |
| `ark-solr` | solr:9 (cloud) | interne | recherche plein-texte |
| `ark-garage` | dxflrs/garage:v2.1.0 | `s3.ark.nak0x.dev` (+ 1 host/bucket) | stockage S3 |
| `ark-cantaloupe` | registry.gitlab.teklia.com/iiif/cantaloupe:5.0.7 | `iiif.ark.nak0x.dev`, `uploads.iiif.…`, `ingest.iiif.…` | serveur IIIF |
| `ark-backend` | registry.gitlab.teklia.com/arkindex/backend:1.12.2 | `ark.nak0x.dev` (+ `/api`,`/admin`,…) | API Django (gunicorn) |
| `ark-worker` | …/arkindex/backend:1.12.2 | interne | worker RQ / Ponos |
| `ark-front` | registry.gitlab.teklia.com/arkindex/frontend:1.12.2 | `ark.nak0x.dev` (catch-all) | SPA |

**Flux réseau clés**
- Navigateur → `coolify-proxy` (TLS) → front / backend (split par chemin sur `ark.nak0x.dev`).
- Navigateur → `coolify-proxy` → `s3.ark.nak0x.dev` (URLs S3 présignées) et `iiif.ark.nak0x.dev` (images).
- Backend → **hairpin** : `https://s3.ark.nak0x.dev` → IP publique → `coolify-proxy` → Garage.
- Cantaloupe → Garage en interne : `http://ark-garage:3900` (pas de TLS, réseau `ark`).

**Répartition des hostnames** (tous résolus par le wildcard DNS `*.nak0x.dev`) :
- `ark.nak0x.dev`
- `s3.ark.nak0x.dev` + `<bucket>.s3.ark.nak0x.dev` (9 buckets : staging, thumbnails, export, training, ponos-logs, ponos-artifacts, ingest, uploads, iiif-cache)
- `iiif.ark.nak0x.dev`, `uploads.iiif.ark.nak0x.dev`, `ingest.iiif.ark.nak0x.dev`

---

## 2. Prérequis

- Serveur Linux avec Docker + Coolify (proxy Traefik sur 80/443).
- Domaine avec **entrées DNS pointant vers l'IP** pour tous les hostnames ci-dessus.
  Ici, un **wildcard DNS `*.nak0x.dev`** couvre tout, y compris les sous-domaines profonds
  (`uploads.iiif.ark.nak0x.dev`).
- Images Teklia **publiques** (pull anonyme, aucun login registry requis).

### ⚠️ Contrainte structurante : pas de certificat wildcard
Le Traefik de Coolify n'utilise que le **challenge HTTP-01** (`acme.httpchallenge=true`), qui **ne peut
pas émettre de certificats wildcard** (`*.s3.…`). Or Arkindex, en conf par défaut, sert S3/IIIF via
des sous-domaines wildcard. **Solution** : l'ensemble des hostnames d'Arkindex est *fini et connu*, on
les **énumère explicitement** dans les règles `Host(...)` Traefik → un cert HTTP-01 par hostname.

---

## 3. Fichiers du dépôt

| Fichier | Rôle |
|---|---|
| `docker-compose.yml` | stack pilotée en `docker compose` (CLI) — **actuellement en service** |
| `docker-compose.coolify.yml` | variante pour adoption dans l'UI Coolify (services `ark-*`, volumes `external`) |
| `config.yml` | configuration Arkindex (montée sur `/arkindex.yml`) |
| `garage.toml` | configuration du stockage S3 Garage |
| `cantaloupe.properties` | configuration du serveur IIIF |
| `.secrets.env` | secrets générés (PG_PASS, SECRET_KEY, GK_ID/GK_SECRET, tokens Garage) — **mode 600** |
| `.env` | variables consommées par `docker compose` (substitution `${...}`) |

---

## 4. Procédure de déploiement (reproductible)

### 4.1 Générer les secrets
```bash
mkdir -p ~/arkindex-deploy && cd ~/arkindex-deploy
umask 077
cat > .secrets.env <<EOF
PG_PASS=$(openssl rand -hex 16)
SECRET_KEY=$(openssl rand -base64 48 | tr -d '\n/+=' | head -c 50)
GARAGE_RPC=$(openssl rand -hex 32)
GARAGE_ADMIN_TOKEN=$(openssl rand -hex 24)
GK_ID=GK$(openssl rand -hex 12)
GK_SECRET=$(openssl rand -hex 32)
EOF
```
Puis créer `.env` (PG_PASS, GK_ID, GK_SECRET), `garage.toml`, `cantaloupe.properties`, `config.yml`
à partir des valeurs de `.secrets.env` (cf. fichiers du dépôt).

### 4.2 IMPORTANT — permissions des fichiers montés
Le backend tourne en **uid 2000 (`arkindex`)**. Avec `umask 077`, les fichiers sont en `600` (uid 1000)
→ le conteneur ne peut pas les lire. **Les passer en 644** :
```bash
chmod 644 config.yml cantaloupe.properties garage.toml
```

### 4.3 Démarrer l'infra de base + initialiser Garage
```bash
docker compose up -d db redis solr garage
```
Garage doit être initialisé (layout + import de la clé S3 + création des 9 buckets). `bootstrap` étant
dev-only (cf. §5), on le fait à la main :
```bash
set -a; . ./.secrets.env; set +a
NODE=$(docker exec ark-garage /garage status | awk '/NO ROLE ASSIGNED/{print $1}')
docker exec ark-garage /garage layout assign -z dev -c 1G "$NODE"
docker exec ark-garage /garage layout apply --version 1
docker exec ark-garage /garage key import --yes -n arkindex "$GK_ID" "$GK_SECRET"
for b in uploads ingest export iiif-cache ponos-artifacts ponos-logs staging thumbnails training; do
  docker exec ark-garage /garage bucket create "$b"
  docker exec ark-garage /garage bucket allow --read --write --owner --key "$GK_ID" "$b"
done
```

### 4.4 Démarrer le backend + migrations
```bash
docker compose up -d backend
docker exec ark-backend arkindex migrate
```

### 4.5 Équivalent de `bootstrap` (ImageServers + farm Ponos), avec le VRAI domaine
```bash
docker exec -i ark-backend arkindex shell <<'PYEOF'
from arkindex.images.models import ImageServer
from arkindex.ponos.models import Farm
for sid, url, bucket, name in [
    (12345, "https://uploads.iiif.ark.nak0x.dev/iiif/2", "uploads", "Local uploads IIIF server"),
    (67890, "https://ingest.iiif.ark.nak0x.dev/iiif/2",  "ingest",  "Ingest IIIF server"),
]:
    ImageServer.objects.update_or_create(id=sid, defaults=dict(url=url, s3_bucket=bucket, s3_region="local", display_name=name))
Farm.objects.update_or_create(
    id="001e411a-1111-2222-3333-444455556666",
    defaults=dict(name="Bootstrap farm", seed="b12868101dab84984481741663d809d2393784894d6e807ceee0bd95051bf971"))
print("OK")
PYEOF
```

### 4.6 Démarrer le reste
```bash
docker compose up -d cantaloupe front worker
```

### 4.7 Créer le compte admin
```bash
docker exec -i -e E=ton@mail -e P="$(openssl rand -base64 18 | tr -d '/+=' | head -c 20)" ark-backend arkindex shell <<'PYEOF'
import os; from django.contrib.auth import get_user_model
U = get_user_model()
u = U.objects.create_superuser(email=os.environ["E"], display_name="admin", password=os.environ["P"])
u.verified_email = True
for f in ["can_upload_s3_image","can_create_iiif_image","can_ingest","can_manage_workers","can_create_worker_version","can_validate_images"]:
    setattr(u, f, True)
u.save(); print("admin créé:", u.email)
PYEOF
```
> Le modèle User d'Arkindex n'a **pas** `is_superuser` (Django), mais `is_admin`. `create_superuser`
> pose `is_admin=True`. Récupérer le mot de passe affiché et le changer.

---

## 5. Problèmes rencontrés → correctifs

### P1 — Version d'image inexistante (`manifest unknown`)
**Symptôme** : `docker pull …/backend:1.13.0` → `manifest unknown`, alors que `1.13.0` apparaît dans
la liste des tags.
**Cause** : le tag listé était `1.13.0-rc1` ; l'extraction du cœur numérique donnait « 1.13.0 » qui
n'existe pas en release finale.
**Fix** : filtrer les tags `-rc/-beta/-post/-alpha` et vérifier l'existence du manifeste. Dernière
**finale** = **1.12.2**.
```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 — Certificats wildcard impossibles
**Symptôme** : Arkindex veut `*.s3.ark…` et `*.iiif.ark…`, mais Coolify ne fait que du HTTP-01.
**Fix** : énumérer explicitement chaque hostname dans une règle `Host(...) || Host(...)` unique par
service (Garage, Cantaloupe) → Traefik émet un cert par host. Le wildcard **DNS** `*.nak0x.dev`
existant fait résoudre tous ces noms sans config DNS supplémentaire.

### P3 — `PermissionError: /arkindex.yml`
**Symptôme** : backend crash au boot, ne peut pas lire le fichier de conf monté.
**Cause** : `umask 077` → `config.yml` en `600` (uid 1000) ; backend en uid 2000.
**Fix** : `chmod 644 config.yml cantaloupe.properties garage.toml`.

### P4 — `redis.exceptions.AuthenticationError` sur le worker  ⭐ (le plus subtil)
**Symptôme** : le worker plante avec « HELLO must be called with the client already authenticated ».
**Cause** : sur le réseau partagé `coolify`, le nom de service générique `redis` **entrait en
collision** avec le conteneur `coolify-redis` (protégé par mot de passe). Le worker se connectait au
mauvais Redis.
**Diagnostic** :
```bash
docker exec ark-worker getent hosts redis      # -> IP de coolify-redis (mauvais)
docker exec ark-worker getent hosts ark-redis   # -> IP correcte
```
**Fix** : dans `config.yml`/`cantaloupe.properties`, référencer les services internes par leur
**nom de conteneur unique** `ark-database`, `ark-redis`, `ark-solr`, `ark-garage` (jamais `db`/`redis`).

### P5 — `bootstrap` inutilisable en production
**Symptôme** : `arkindex bootstrap` refuse (`You cannot run this script in production.`) et code les
URLs en `*.ark.localhost`.
**Fix** : répliquer ses 3 actions à la main avec le vrai domaine (cf. §4.3 et §4.5) : init Garage,
2 ImageServers (id 12345 uploads / 67890 ingest), farm Ponos. La clé S3 « placeholder » (`GKAAA…`) de
bootstrap est remplacée par une **clé aléatoire** propre.

### P6 — Adressage S3 virtual-host (et non path-style)
**Cause** : le backend force `addressing_style="auto"` (boto3) → URLs `<bucket>.s3.ark…` (pas
`s3.ark…/<bucket>`). Pas d'option pour path-style.
**Fix** : énumérer les 9 sous-domaines de bucket dans la règle Traefik de Garage + conserver
`root_domain = ".s3.ark.nak0x.dev"` dans `garage.toml` pour que Garage mappe sous-domaine → bucket.
Vérifié : le backend écrit/lit/supprime via `https://s3.ark.nak0x.dev` (hairpin + TLS OK).

### P7 — Gunicorn lance trop de workers
**Symptôme** : 9 workers gunicorn (= `nproc*2+1`) → trop de RAM sur ce VPS.
**Fix** : `MAX_WORKERS: "3"` dans l'environnement du backend.

### P8 — Fichiers statiques admin/swagger non servis
**Cause** : pas de WhiteNoise ; en prod les statics viennent d'un **CDN**.
**Fix** : `static.cdn_assets_url: https://assets.teklia.com/arkindex` dans `config.yml`.
**Note** : purement cosmétique (admin Django/DRF stylés) — l'API et la SPA n'en dépendent pas. Le
chemin CDN testé renvoyait 404 → l'admin peut rester sans style, sans impact fonctionnel.

### P9 — Collection Solr
`arkindex reindex --setup` exige un corpus : les collections Solr sont créées **par corpus**
(`project-<uuid>`) à la volée lors de l'indexation. **Rien à pré-créer.**

### P10 — Backend sans Pillow (test uniquement)
Générer une image de test via le backend échoue (`No module named 'PIL'`, le traitement image est côté
workers). Pour tester : générer le JPEG hors backend et l'uploader via un conteneur `amazon/aws-cli`.

### P11 — Coolify écrase `container_name` (pour l'adoption UI)
**Cause** : Coolify renomme les conteneurs en `<service>-<uuid>` mais **garde le nom de service** comme
alias DNS.
**Fix** : dans `docker-compose.coolify.yml`, **renommer les services** en `ark-*` (uniques → pas de
collision, cf. P4) et déclarer les volumes en `external` (noms existants `arkindex-deploy_*`) pour ne
rien perdre.

---

## 6. Vérifications (santé de bout en bout)
```bash
# API + TLS public
curl -sS -o /dev/null -w "%{http_code} tls=%{ssl_verify_result}\n" https://ark.nak0x.dev/api/v1/health/
# Login admin -> 201 + auth_token
curl -sS -X POST https://ark.nak0x.dev/api/v1/user/login/ -H 'Content-Type: application/json' \
  -d '{"email":"ton@mail","password":"…"}' -w "\n%{http_code}\n"
# S3 (backend) — write/read/delete via l'endpoint public (hairpin)
docker exec -i ark-backend arkindex shell <<'PY'
from arkindex.project.aws import s3
o=s3.Bucket("staging").Object("hc.txt"); o.put(Body=b"ok"); print(o.get()["Body"].read()); o.delete()
PY
# IIIF : uploader une image dans le bucket 'uploads' puis
curl -sS -o /dev/null -w "%{http_code}\n" "https://uploads.iiif.ark.nak0x.dev/iiif/2/<key>/info.json"
# RAM
free -h; docker stats --no-stream --format 'table {{.Name}}\t{{.MemUsage}}' | grep ark-
```

---

## 7. Adoption dans l'UI Coolify — ✅ FAIT

La stack est désormais une ressource **gérée par Coolify** : projet **arkindex**, service **arkindex**
(uuid `tdquwauzxsq0985fk9kjqqys`), conteneurs `ark-*-tdquwauzxsq0985fk9kjqqys`. Source =
`docker-compose.coolify.yml`. Pilotage (deploy/logs/restart) via le dashboard Coolify.

### Procédure suivie (API Coolify)
```bash
TOKEN=$(cat ~/.ark_coolify_token)
# 1) projet + récup environnement production
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"arkindex"}' http://localhost:8000/api/v1/projects
# 2) créer le service (docker_compose_raw en BASE64 obligatoire), instant_deploy=false
#    body: server_uuid, project_uuid, environment_name/uuid, name, docker_compose_raw(b64)
# 3) renseigner les secrets en variables d'env du service (PATCH .../envs) : PG_PASS, GK_ID, GK_SECRET
# 4) arrêter la stack CLI puis déployer UNE SEULE FOIS :
cd ~/arkindex-deploy && docker compose down          # garde les volumes en backup
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/deploy?uuid=tdquwauzxsq0985fk9kjqqys"
```

### ⚠️ Points d'attention (cf. aussi P11)
- **Coolify remappe les volumes nommés** en `<uuid>_*` et **ignore `external:`** → au premier
  déploiement la stack repart sur des **volumes vides**. Comme il n'y avait pas encore de données
  réelles, on a simplement **ré-initialisé** (Garage + `migrate` + image servers + admin) contre les
  conteneurs Coolify (`docker exec ark-backend-<uuid> …`). Les anciens volumes `arkindex-deploy_*`
  restent en backup (supprimables : `docker volume rm arkindex-deploy_pgdata …`).
- **Coolify préserve** : réseau `coolify` externe, labels Traefik, montages bind **absolus**, et les
  **noms de service** (alias DNS `ark-*`). Il écrase `container_name` en `<service>-<uuid>`.
- **Ne déclencher le deploy qu'une fois** (POST *ou* GET, pas les deux) — sinon double déploiement.

---

## 8. Commandes de maintenance
```bash
cd ~/arkindex-deploy
docker compose ps                      # état
docker compose logs -f backend         # logs
docker compose restart backend         # redémarrer un service
docker exec -it ark-backend arkindex shell   # shell Django
docker exec ark-backend arkindex migrate     # migrations (après upgrade d'image)
# Mise à jour de version : changer le tag dans le compose puis
docker compose pull backend front worker && docker compose up -d
```

## 9. Réserves / points d'attention
- **RAM** : VPS 8 Go déjà chargé ; Arkindex ≈ 1 Go réel (Solr = plus gros). Swap 4 Go présent. Si
  instable, désactiver Solr (`features.search: no` + retirer le service) est la soupape.
- **Socket Docker du worker** : monté + `user: root` (requis pour les tâches Ponos/ML). Point sécurité
  à garder en tête ; les workers ML tirent de grosses images (hors périmètre de ce déploiement initial).
- **Édition Community** (AGPL), pas de licence Enterprise.