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.
Quand l’utiliser
Section intitulée « Quand l’utiliser »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.
Prérequis
Section intitulée « 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. |
Topologie
Section intitulée « Topologie »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.
Topologie de la base de données
Section intitulée « Topologie de la base de données »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
replicaen lecture seule, facultatif. Chaque pool en lecture seule exécuteSET 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_mss’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é.
-
Provisionnez les magasins d’état. Installez PostgreSQL 14 ou plus récent, et Redis. Créez une base vide pour le premier déploiement.
-
Mettez le fichier de configuration en place. Réglez
event.urlsur l’adresse Redis etDATABASE_URLdans l’environnement. Voir Fichiers de configuration. -
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.
-
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"]Dépannage
Section intitulée « Dépannage »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.
Voir aussi
Section intitulée « Voir aussi »-
Déployer avec des conteneurs — les images et l’entrée TLS.
-
Déployer en production — le pas-à-pas à
copier-coller.
-
Fichiers de configuration — chaque clé que prend le fichier de configuration.
-
Migrations de base de données — comment le schéma atteint la base.
-
Architecture en un coup d’œil — les concepts derrière les services.
-
Internes sur GitHubà : container-images.md, first-deployment.md, config.md.