Installer avec Docker

Lancer Linkr avec les images publiées sur Docker Hub : un fichier Compose, une clé secrète, une commande.

En résumé

Un fichier à télécharger, une clé à générer, une commande : Linkr tourne, avec toutes ses fonctionnalités. Ni dépôt à cloner, ni code à compiler. C’est la méthode recommandée, pour essayer Linkr comme pour le déployer sur un serveur.

Prérequis

Docker : Docker Desktop sur Mac et Windows, Docker Engine sur Linux.
Environ 1 Go d’espace disque.

Installation

Ouvrez un terminal (Terminal sur macOS, PowerShell sur Windows) dans un dossier dédié à Linkr.

Télécharger le fichier Compose

curl -O https://framagit.org/interhop/linkr/linkr/-/raw/main/docker/docker-compose.hub.yml

Invoke-WebRequest -Uri https://framagit.org/interhop/linkr/linkr/-/raw/main/docker/docker-compose.hub.yml -OutFile docker-compose.hub.yml

Générer la clé secrète

À faire une seule fois : la commande écrit la clé dans un fichier .env, que Docker relit à chaque lancement.

echo "LINKR_SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')" > .env

$b = New-Object byte[] 48
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b)
"LINKR_SECRET_KEY=$([Convert]::ToBase64String($b))" | Out-File -Encoding ascii .env

Lancer Linkr

Le premier lancement télécharge les images (environ 780 Mo).

docker compose -f docker-compose.hub.yml up

Ouvrir Linkr

Rendez-vous sur http://localhost:3000 et suivez l’assistant de configuration : il vous fait créer le compte administrateur et propose d’installer des données de démonstration.

C'est installé

Linkr tourne. Les sections suivantes sont à consulter au besoin : ce que fait l’assistant, où vivent vos données, comment changer de version.

L’assistant de premier démarrage

La toute première ouverture ne présente pas la page de connexion mais un assistant en trois étapes — il n’y a encore aucun utilisateur. Les visites suivantes affichent la page de connexion habituelle.

Base de données

L'assistant affiche la base que le serveur utilise. Cet écran est en lecture seule : la base se configure côté serveur via LINKR_DATABASE_URL, et elle est créée automatiquement. Pour en changer, modifiez la configuration serveur et redémarrez.

Créer un compte administrateur

Ce sera le premier compte administrateur de l'instance. Renseignez un nom d'utilisateur et un mot de passe. Dans un build de développement les champs sont pré-remplis avec admin / admin ; un build de production démarre avec des champs vides.

Données par défaut

Dernière étape : installer l'espace de démonstration, qui contient une base OMOP, des alignements de concepts, un pipeline ETL et des projets d'exemple. Cliquez sur « Installer et terminer », ou sur « Démarrer à vide » pour partir d'une instance vierge. Ce choix n'est pas définitif : le contenu s'installe ou se supprime plus tard depuis la page Catalogue.

Créer l'administrateur en ligne de commande

Pour une installation scriptée, l'assistant peut être court-circuité en appelant directement l'API :

curl localhost:8000/api/v1/setup/status

curl -X POST localhost:8000/api/v1/setup/initialize \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"un-mot-de-passe-solide"}'

La première commande répond {"needs_setup": true} tant que l'instance n'est pas initialisée.

Arrêter et relancer

Lancé comme ci-dessus, Linkr occupe le terminal : Ctrl+C l’arrête. Pour qu’il tourne en arrière-plan, ajoutez -d, puis arrêtez-le avec down :

docker compose -f docker-compose.hub.yml up -d
docker compose -f docker-compose.hub.yml down

Un arrêt ne touche pas à vos données : elles vivent en dehors des conteneurs.

La clé secrète

Elle signe les jetons de connexion et chiffre les mots de passe des bases de données que vous enregistrez dans Linkr. Le serveur refuse de démarrer sans elle.

Gardez-la stable : en changer déconnecte tout le monde et rend illisibles les mots de passe déjà enregistrés. Ne partagez pas le fichier .env, et conservez-le avec le fichier Compose : si vous déplacez Linkr ou changez de machine, ce sont ces deux fichiers, plus le dossier de données, qu’il faut emporter.

Où vivent vos données

Par défaut, tout ce que vous créez est rangé dans un volume Docker nommé linkr-data. Il survit aux redémarrages, aux docker compose down et aux mises à jour — mais il appartient à Docker : vous ne pouvez ni l’ouvrir dans votre explorateur de fichiers, ni le copier avec vos outils habituels.

Dès que les données comptent — plusieurs utilisateurs, un serveur, quoi que ce soit à sauvegarder — montez plutôt un vrai dossier. Dans docker-compose.hub.yml, remplacez la ligne du volume par un chemin à vous :

    volumes:
      - ./linkr-data:/root/.linkr     # à côté du fichier Compose
      # - /srv/linkr:/root/.linkr     # ou un chemin serveur

Docker crée le dossier s’il n’existe pas. Vous y retrouverez la base et l’ensemble des fichiers, sauvegardables par une simple copie.

down -v efface un volume, jamais un dossier

docker compose down -v supprime le volume nommé, donc toutes vos données. Un dossier monté n’est jamais touché par cette commande — une raison de plus de lui préférer un vrai chemin dès que le contenu compte.

Changer de version

Le fichier téléchargé désigne une version précise : votre instance ne change que lorsque vous le décidez. Les deux lignes image: portent ce numéro, et Linkr l’affiche dans sa barre d’état.

Pour passer à une version plus récente, remplacez le numéro sur les deux lignes — les versions publiées sont listées sur Docker Hub — puis relancez :

docker compose -f docker-compose.hub.yml pull
docker compose -f docker-compose.hub.yml up -d

Vos données restent en place, et les migrations de base s’appliquent automatiquement au redémarrage.

Les deux images avancent ensemble

Frontend et backend inscrivent la même version de format dans les données exportées : un couple dépareillé produit des exports incohérents. Les deux lignes doivent toujours porter le même numéro.

Dépannage

Docker Compose refuse de démarrer sur LINKR_SECRET_KEY. Le fichier .env est absent, vide, ou n’est pas dans le même dossier que docker-compose.hub.yml. Reprenez l’étape 2 depuis ce dossier.

python3 : command not found à l’étape 2. Python ne sert qu’à générer la clé : openssl rand -base64 48 produit une valeur tout aussi valable. Écrivez-la dans .env sous la forme LINKR_SECRET_KEY=la-valeur.

Port 3000 déjà pris. Fermez le programme qui l’occupe (lsof -i :3000 sur macOS/Linux pour le trouver), ou changez le port dans docker-compose.hub.yml : le premier nombre de la ligne "3000:80". Reportez alors la nouvelle adresse dans LINKR_CORS_ORIGINS, dans le même fichier.

Lent, ou refus de démarrer, sur un Mac Apple Silicon. Les images sont compilées pour l’architecture amd64 ; Docker les fait tourner en émulation, plus lentement. S’il refuse de démarrer un conteneur, ajoutez platform: linux/amd64 sous chaque service. Pour un usage quotidien sur ce type de machine, l’installation manuelle reste plus confortable.

Les données ont disparu après un down -v. Cette commande supprime le volume nommé, sans récupération possible. Montez un vrai dossier pour que cela ne puisse plus arriver — voir « Où vivent vos données ».

Pour aller plus loin

Déployer sur un serveur, avec un vrai nom de domaine et HTTPS : Installation en production.
Créer votre premier projet : Votre premier projet.