Migrer le stack Docker du PC vers le VPS

TL;DR — Ne transférez pas les containers Windows. Recréez le stack sur le VPS depuis le code source (docker compose up --build). Transférez uniquement les données (Postgres + images de cartes) si vous voulez sauter la phase d'ingestion.

Pourquoi recréer plutôt que transférer

Vous avez deux options :

Option	Description	Verdict
A. Transférer les containers	docker save des images + copie des volumes via SSH	À éviter
B. Recréer depuis le code (IaC)	git clone + docker compose up --build sur le VPS	Recommandé

Recréer (option B) — pourquoi c'est mieux

1. Tout est déjà reproductible — le compose.yml, les *.Dockerfile et le code source sont versionnés dans tcg-collector-backend/. Le VPS sait déjà builder le stack.
2. Plus léger — vous ne transférez ni les ~5 GB d'images Docker, ni les caches buildkit. Le VPS ne tire que les bases (pgvector/pgvector:pg16, nginx:alpine, node:22-alpine) et compile les couches custom à partir d'un repo de quelques MB.
3. Plus propre — pas d'accumulation de couches obsolètes (le container tcg-collector-ingest-1 exited depuis 5 jours, l'ancien sidecar embeddings probablement remplaçable, le réseau solidity-dojo_default orphelin… tout repart à zéro).
4. Évite les pièges OS — copier un data/pg cru de Docker Desktop (WSL2) vers Linux marche en pratique mais reste fragile (pg_dump est la voie sûre, voir plus bas).
5. Prêt pour l'avenir — chaque modification future passera par un git pull && docker compose up -d --build sur le VPS, pas par un nouveau transfert manuel.

Transférer (option A) — quand ça vaut le coup

Uniquement si toutes ces conditions sont vraies :

• Vous avez modifié l'état applicatif manuellement (data hors ingestion).
• Re-télécharger via TCGdex serait trop long ou rate-limité côté VPS.
• Vous êtes pressé de mettre le service en ligne.

Dans ce cas, ne transférez pas les containers, mais seulement les données : pg_dump + tar des images (voir §3).

---

1. Préparer le VPS

Pré-requis supposés en place sur le VPS :

• Docker Engine + plugin compose installés.
• Utilisateur kael dans le groupe docker.
• gh installé et authentifié.
• Repo snag-tcg/tcg-collector-backend clonable.

Vérifier avant tout :

docker compose version
docker run --rm hello-world

2. Recréer le stack — voie nominale

# 1. Cloner (si pas déjà fait)
mkdir -p ~/skn-tcg && cd ~/skn-tcg
gh repo clone snag-tcg/tcg-collector-backend
cd tcg-collector-backend

# 2. Configurer l'environnement
cp .env.example .env
# Éditer .env :
#   - PGUSER / PGPASSWORD (un mot de passe FORT, pas "tcg")
#   - API_WRITE_TOKEN (token aléatoire si /scan ou writes exposés)
#   - CORS_ORIGIN (domaine du front, pas "*" en prod)
nano .env

# 3. Lancer le stack
docker compose -f docker/compose.yml up -d --build

# 4. Vérifier
docker compose -f docker/compose.yml ps
docker compose -f docker/compose.yml logs -f api
curl http://localhost:8080/health   # ou via nginx : :8081/api/health

# 5. Première ingestion (long — selon INGEST_SETS)
docker compose -f docker/compose.yml run --rm ingest

Builds attendus : ~5 à 15 min selon CPU du VPS (le plus long = tcg-vision qui télécharge ~85 MB de poids DINOv2 et build PyTorch CPU).

3. Transférer les données (optionnel — si vous voulez sauter l'ingestion)

Faites-le après que le stack tourne sur le VPS, en remplaçant uniquement le contenu de Postgres et le dossier data/images.

3.1 Postgres — pg_dump (méthode propre, recommandée)

Sur le PC Windows :

# Dump complet (compressé, format custom)
docker exec tcg-collector-postgres-1 `
  pg_dump -U tcg -d tcg -Fc -Z 9 -f /tmp/tcg.dump
docker cp tcg-collector-postgres-1:/tmp/tcg.dump .\tcg.dump

# Envoyer sur le VPS
scp .\tcg.dump kael@VPS_IP:/tmp/tcg.dump

Sur le VPS :

# Stack déjà démarré, mais vide
docker cp /tmp/tcg.dump tcg-collector-postgres-1:/tmp/tcg.dump

# Restaurer
docker exec -i tcg-collector-postgres-1 \
  pg_restore -U tcg -d tcg --clean --if-exists --no-owner /tmp/tcg.dump

Pourquoi pas un copier-coller du dossier data/pg ? Ça marche souvent (même version pg16), mais c'est fragile : différences d'endianness, locale, page size, pg_control corrompu en cours de copie. pg_dump est portable et version-tolérant.

Note sur la corruption d'index détectée dans le data/pg du PC (voir container-inventory.md) : pg_dump lit logiquement les tables, donc le dump régénère des index propres côté VPS. C'est un avantage net du dump par rapport à la copie brute.

3.2 Images de cartes — tar + scp (ou rsync)

Les ~1.9 GB de visuels sont des fichiers statiques régénérables, mais long à re-télécharger.

# Sur Windows, depuis tcg-collector-backend\
tar -czf data-images.tar.gz data\images
scp data-images.tar.gz kael@VPS_IP:/tmp/

Sur le VPS :

cd ~/snag-tcg/tcg-collector-backend
tar -xzf /tmp/data-images.tar.gz   # recrée data/images/
sudo chown -R $USER:$USER data/images

Le service nginx du compose monte déjà ../data/images ; un simple docker compose restart nginx suffit à le rendre actif.

3.3 Index pHash & FAISS

• L'index pHash (scanIndex.json) est généré dans le repo sibling poc-tcg-collector (npm run ingest:cards). Pas besoin de migrer : régénérez-le sur le VPS si vous y déployez aussi le client RN, sinon laissez-le côté machine de build.
• L'index FAISS du sidecar tcg-vision est prébuilt dans l'image Docker (docker/tcg-vision.Dockerfile clone un commit pinned de KaelSensei/tgc-app). Aucune action manuelle.

4. Faut-il garder l'ancien sidecar embeddings ?

Probablement non — tcg-vision le remplace fonctionnellement avec une approche plus complète. Avant de couper :

1. Grep dans le code de l'API : EMBEDDINGS_URL est-il encore lu ?
2. Si oui, lit-il l'ancien embeddings ou pointe-t-il sur tcg-vision ?
3. Si l'ancien n'est plus consommé, retirer le service embeddings du compose.yml côté VPS dès le départ. Économie : ~1.25 GB d'image, RAM en moins.

5. Production — checklist sécurité minimale

À configurer côté VPS, avant d'exposer publiquement :

• .env : mot de passe Postgres fort, API_WRITE_TOKEN long et aléatoire, CORS_ORIGIN restreint au domaine du front.
• Ne pas exposer le port 5432 publiquement. Dans compose.yml, lier explicitement à localhost :

  ports:
    - "127.0.0.1:5432:5432"

• Reverse proxy TLS (Caddy / Traefik / nginx host) devant :8080 et :8000. Pas d'API en clair.
• UFW / iptables : n'ouvrir que 22/tcp (SSH) + 80/tcp + 443/tcp.
• Rate-limit côté nginx ou côté Fastify (API_RATE_LIMIT_MAX).
• docker compose ... up -d au démarrage du serveur via systemd (le restart: unless-stopped du compose suffit après un premier up).

6. Ordre d'exécution recommandé

1. Réparer la corruption d'index sur le PC (optionnel — pour avoir un état sain à dumper).
2. Sur le VPS : compléter les pré-requis de provisioning listés en §1, puis cloner le repo.
3. cp .env.example .env + édition des secrets.
4. docker compose up -d --build (laisse Postgres + nginx + api + tcg-vision tourner à vide).
5. Au choix :
   • Sans transfert : docker compose run --rm ingest → laisser tourner ~30 min.
   • Avec transfert : pg_dump + pg_restore + tar/scp des images (§3).
6. Health-checks : curl /api/health, curl :8000/health, scan d'une carte test.
7. Mettre les ports privés derrière un reverse proxy + TLS (§5).

7. Une fois en place — workflow récurrent

Plus de transferts ! Le pattern devient :

# Sur le VPS
cd ~/snag-tcg/tcg-collector-backend
git pull
docker compose -f docker/compose.yml up -d --build

Si une nouvelle ingestion est nécessaire (nouveaux sets) : docker compose run --rm ingest.