Auto-hébergement on Documentation Seurch

Prérequis

Mon, 01 Jan 0001 00:00:00 +0000

Prérequis#

Environnement d’exécution#

Composant	Notes
Un moteur de conteneurs	Docker ou Podman, pour exécuter l’image publiée.
PostgreSQL	La base de données applicative. Tout PostgreSQL raisonnablement récent (16+) convient.
Une clé API Brave Search	Le minimum pour des résultats utiles, voir Fournisseurs de recherche. Le niveau gratuit suffit pour commencer.
HTTPS sortant	Le serveur appelle les fournisseurs amont ; si vous êtes derrière une liste blanche, voir les hôtes des fournisseurs.

Tout le reste — serveur web, service des fichiers statiques et compilation des catalogues de traduction — est intégré dans l’image.

Démarrage rapide

Mon, 01 Jan 0001 00:00:00 +0000

Démarrage rapide#

Le moyen le plus rapide d’avoir une instance opérationnelle est l’image Docker. Vous avez besoin d’une base de données PostgreSQL et, au minimum, d’une clé API Brave Search.

Avec Docker#

docker run -p 8000:8000 \
 -e SECRET_KEY=votre-long-secret-aléatoire \
 -e DATABASE_URL=postgres://utilisateur:motdepasse@hôte-db:5432/seurch \
 -e ALLOWED_HOSTS=search.example.com \
 -e BRAVE_API_KEY=votre-clé-brave \
 -e BRAVE_SUGGEST_API_KEY=votre-clé-brave-suggest \
 -e MARGINALIA_API_KEY=public \
 seurch

Au démarrage, le conteneur :

Applique les migrations de base de données (sans effet une fois le schéma à jour).
Sert l’application avec gunicorn (2 workers) sur le port 8000.
Sert ses propres fichiers statiques via WhiteNoise (compressés et hachés), sans serveur web séparé ni CDN requis.
Répond à une vérification de santé sur /up.

Les catalogues de traduction et les fichiers statiques sont compilés à la construction, il n’y a donc rien d’autre à lancer.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Configuration#

Seurch est entièrement configuré via des variables d’environnement (en production) ou un fichier .env (en développement). Le dépôt inclut un fichier .env.example documentant chaque variable ; cette page en est la référence.

Noyau#

Variable	Rôle	Notes
`SECRET_KEY`	Clé secrète Django	Requise en production. Longue et aléatoire.
`DEBUG`	Mode débogage	Maintenez `False` (la valeur par défaut) en production.
`ALLOWED_HOSTS`	Noms d’hôtes séparés par des virgules que l’application servira	ex. `search.example.com`.
`DATABASE_URL`	URL de connexion PostgreSQL	ex. `postgres://utilisateur:mdp@hôte:5432/seurch`.
`LOG_LEVEL`	Verbosité des logs	`DEBUG` / `INFO` / `WARNING` / `ERROR` (par défaut `INFO`).

Fournisseurs de recherche#

Ces clés déterminent quels moteurs, onglets de médias et fiches de connaissance sont disponibles. Un fournisseur sans clé est simplement masqué (pas affiché comme cassé). Détails complets dans Fournisseurs de recherche.

Fournisseurs de recherche

Mon, 01 Jan 0001 00:00:00 +0000

Fournisseurs de recherche#

Seurch mélange les résultats de plusieurs fournisseurs indépendants. Les onglets et fiches qui apparaissent dépendent des clés que vous définissez. Un fournisseur sans clé est masqué ; l’onglet ou la fiche concerné n’apparaît tout simplement pas, plutôt que d’afficher une erreur.

Tous les appels amont se font côté serveur ; les clés ne sont jamais exposées au navigateur.

Cette page est l’aperçu indiquant quelle clé active quoi. Pour les instructions d’inscription pas à pas pour chaque fournisseur, voir Obtenir les clés API.

Obtenir les clés API

Mon, 01 Jan 0001 00:00:00 +0000

Obtenir les clés API#

Guides pas à pas pour obtenir la clé de chaque fournisseur. Aucune n’est requise pour démarrer Seurch, mais au moins un moteur web (Brave est le plus simple) est nécessaire pour des résultats utiles. Chaque fournisseur que vous ignorez masque simplement son onglet ou sa fiche ; voir Fournisseurs de recherche pour ce que chacun active.

Une fois que vous avez une clé, définissez la variable d’environnement correspondante (voir Configuration) et redémarrez l’application.

Traduction

Mon, 01 Jan 0001 00:00:00 +0000

Traduction (LibreTranslate)#

L’onglet Traduction est alimenté par LibreTranslate, un serveur de traduction automatique open source et auto-hébergeable. Seurch l’appelle côté serveur ; aucun service de traduction tiers n’est impliqué.

Activer l’onglet#

Pointez Seurch vers une instance LibreTranslate avec LIBRETRANSLATE_URL :

LIBRETRANSLATE_URL=http://libretranslate:5000

Définissez-la et l’onglet Traduction (ainsi que son paramètre) apparaissent, avec les langues que cette instance propose.
Laissez-la non définie et l’onglet Traduction ainsi que son paramètre sont entièrement désactivés.

Exécuter LibreTranslate#

La pile de développement démarre automatiquement un LibreTranslate local (make up en lance un sur http://localhost:5000). Pour la production, déployez le vôtre, par exemple :

Utilisateurs et accès

Mon, 01 Jan 0001 00:00:00 +0000

Utilisateurs et accès#

Seurch est accessible uniquement par connexion et sans inscription publique, donc en tant qu’administrateur, vous contrôlez qui a un compte. C’est ce qui maintient une instance privée pour vos utilisateurs.

Créer des comptes#

Créez des utilisateurs avec la commande de gestion standard de Django :

# Docker
docker exec -it <conteneur> python manage.py createsuperuser

# Depuis les sources
make superuser

createsuperuser crée un compte administrateur ; pour les utilisateurs ordinaires, vous pouvez les créer de la même façon (ou depuis l’administration Django une fois que vous avez un superutilisateur). Chaque compte nécessite un nom d’utilisateur et un mot de passe ; un e-mail est optionnel (voir ci-dessous).

Clés API

Mon, 01 Jan 0001 00:00:00 +0000

Clés API#

Les utilisateurs accèdent à l’API publique avec des clés API par utilisateur. Les utilisateurs peuvent gérer leurs propres clés dans l’interface web (Paramètres → Clés API), et vous pouvez les gérer depuis la ligne de commande.

Comment les clés sont stockées#

Une clé ressemble à seurch_sk_<préfixe>.<secret> :

Le préfixe (8 caractères) est stocké en clair pour une recherche rapide.
Seul un hachage SHA-256 du secret est stocké, jamais le secret lui-même.

Ainsi, la valeur complète d’une clé est affichée exactement une fois, à la création, et ne peut pas être récupérée par la suite, uniquement révoquée.

Maintenance

Mon, 01 Jan 0001 00:00:00 +0000

Maintenance#

Seurch nécessite peu de maintenance continue, mais quelques commandes de gestion permettent de le garder propre et à jour. Exécutez-les selon un planning (tâche cron, minuteur systemd ou fonctionnalité de tâche planifiée de votre orchestrateur). Exécutez chacune à l’intérieur du conteneur (docker exec <conteneur> python manage.py …) ou via make / uv run depuis les sources.

Tâches planifiées#

Commande	Ce qu’elle fait	Planning suggéré
`clear_expired_cache`	Supprime les lignes de cache de résultats de recherche expirées	Quotidien
`check_provider_health`	Sonde les fournisseurs avec un point de terminaison de santé gratuit afin que `/status` reste à jour, sans dépenser de quota payant	Toutes les ~10 minutes
`refresh_currency`	Rafraîchit les taux de change mis en cache et purge le cache de réponses instantanées	Quotidien (optionnel, se rafraîchit aussi à la demande)

Un exemple de cron :

Notes de production

Mon, 01 Jan 0001 00:00:00 +0000

Notes de production#

Quelques points importants à connaître lorsque vous déployez Seurch pour de vrais utilisateurs.

L’image#

Sert l’application avec gunicorn (2 workers) sur le port 8000.
Sert ses propres fichiers statiques via WhiteNoise, compressés et hachés ; vous n’avez donc pas besoin d’un serveur de fichiers statiques séparé ni d’un CDN.
Compile les catalogues de traduction et collecte les fichiers statiques au moment de la construction.
Applique les migrations de base de données au démarrage.

Proxy inverse et TLS#

Placez un proxy inverse avec terminaison TLS devant (Caddy, nginx, Traefik, …) et transmettez vers le port 8000. Définissez :