Aller au contenu

Prérequis système et topologie

Facet tient en un binaire backend, un serveur frontend et deux magasins d’état. Le backend garde chaque fait durable dans PostgreSQL. Redis est le bus de réaction. Cette page liste ce qu’un hôte exige et comment les pièces se connectent, pour dimensionner un déploiement avant de le lancer.

Utilisez cette page quandà :

  • Vous planifiez un hôte ou une pile de conteneurs pour Facet.
  • Vous choisissez entre une base unique et un cluster routé.
  • Vous vérifiez une machine face aux prérequis.
Composant Exigence Notes
PostgreSQL 14 ou plus récent La fonction ulid() exige PostgreSQL 14. Une instance suffit pour la plupart des installations.
Redis Requis Le bus d’événements, les sessions, les codes OAuth et les limites de débit l’utilisent. La pile de release fait tourner l’image redis:7.
Fichier de configuration config.{APP_ENV}.yml Le démarrage échoue sans lui. Voir Fichiers de configuration.
Binaire backend Image de release, ou make build_release Migrations, scripts d’événements Lua et corpus d’initialisation voyagent dans le binaire.
Docker avec Compose Pour la voie conteneurs La pile de release compte cinq services. Voir Déployer avec des conteneurs.
Diagram Diagram

La pile de conteneurs fait tourner cinq servicesà :

Service Image Exposé au réseauà?
postgres pgvector/pgvector:0.8.0-pg17 Non
redis redis:7 Non
backend ghcr.io/wearefacet/facet Non — l’entrée achemine vers lui
frontend ghcr.io/wearefacet/facet-frontend Non — l’entrée achemine vers lui
caddy caddy:2 Oui — il publie le port TLS

L’image backend tourne sous l’uid 10001. L’image frontend tourne sous node. Un déploiement depuis les sources remplace les deux images d’application par make build_release et le serveur SvelteKit de dev ou de build — voir Installer pour le développement.

Par défaut, le backend ouvre un pool depuis DATABASE_URL. Chaque lecture et chaque écriture partagent ce pool. La plupart des installations s’arrêtent là.

Une installation plus grande peut répartir la charge avec la table de routage facultative database.cluster. Chaque entrée nomme une base physique et les ressources qu’elle sertà :

  • Une ressource est un id de domaine, une étiquette de sous-système préfixée par $, ou *.

  • Exactement une entrée porte *. Elle sert le plan de contrôle et tout ce qui n’est pas routé.

  • Une ressource précise n’apparaît que dans une seule entrée.

  • Une entrée peut porter un pool replica en lecture seule, facultatif. Chaque pool en lecture seule exécute SET default_transaction_read_only = on, si bien qu’une écriture mal étiquetée échoue bruyamment.

  • Des entrées qui partagent une même URL gardent des pools séparés. Cela donne une isolation de pool sans seconde base.

    database.statement_timeout_ms s’applique à chaque connexion poolée du processus serveur. Les points d’entrée CLI n’ont pas de timeoutà : un DDL long ne peut pas être annulé.

  1. Provisionnez les magasins d’état. Installez PostgreSQL 14 ou plus récent, et Redis. Créez une base vide pour le premier déploiement.

  2. Mettez le fichier de configuration en place. Réglez event.url sur l’adresse Redis et DATABASE_URL dans l’environnement. Voir Fichiers de configuration.

  3. Choisissez la topologie de la base. Commencez avec l’unique pool DATABASE_URL. Ajoutez la table de routage quand un pool ne suffit plus à

    la charge.

  4. Lancez la pile. Prenez la voie conteneurs pour la production — Déployer avec des conteneurs — ou construisez depuis les sources. Le pas-à-pas à copier-coller est Déployer en production.

Une table de routage de cluster avec une base principale et un petit pool de masse. Les deux entrées partagent la même URL, donc le pool de masse n’est qu’une isolation de poolà :

database:
statement_timeout_ms: 5000
cluster:
databases:
main:
url: !env DATABASE_URL
max_pool_size: 20
resources: ["*"]
bulk_pool:
url: !env DATABASE_URL
max_pool_size: 8
resources: ["$bulk"]

Le démarrage échoue et nomme le chemin de configuration.

Le fichier n’existe pas à l’emplacement résolu. Le démarrage ne retombe jamais sur le fichier d’un autre environnement.

Le démarrage échoue avec Missing required config key 'artifact_base_url'.

Ajoutez les clés de premier niveau requises. Voir Fichiers de configuration.

PostgreSQL lève une erreur dans ulid().

Le serveur est plus ancien que PostgreSQL 14. Mettez le serveur à niveau.

Le démarrage échoue avec Missing 'event' key in config.

Ajoutez la section event: avec l’URL Redis. Redis est une dépendance requise.

Les emprunts de connexion attendent sous charge.

Surveillez la métrique facet_db_checkout_total{database, role} et ajustez max_pool_size par entrée. Une écriture imbriquée dans un périmètre de lecture garde deux connexions pendant toute sa durée.