Référence de l'environnement auto-hébergé
Commencez par la version env.example, que vous avez téléchargé en tant que .env dans Commencer. Il s'agit de la plus petite configuration Compose prise en charge. Utiliser env.full.example lorsque vous avez besoin d'un paramètre facultatif ; cette page explique quels paramètres vont ensemble et quand les modifier.
Après édition .env, validez l'interpolation sans imprimer la configuration résolue :
docker compose config --quiet
Ne vous engagez pas .env, collez-le dans les demandes d'assistance ou exposez le résultat de docker compose config: la sortie résolue contient des secrets.
Valeurs de production requises
Générez chaque secret indépendamment avec openssl rand -hex 32. Conservez les anciennes valeurs à chaque mise à niveau et stockez une copie de récupération en dehors du serveur.
| Variable | Valeur de production | Pourquoi c'est important |
|---|---|---|
POSTGRES_PASSWORD | Mot de passe aléatoire unique | Protège la base de données PostgreSQL fournie. |
WEB_ORIGIN | Origine de l'application HTTPS publique, telle que https://kanera.example.com | Utilisé pour les liens de navigateur, CORS et les flux d'authentification. N'incluez pas de barre oblique finale. |
COOKIE_DOMAIN | Nom d'hôte de l'application, tel que kanera.example.com | Portée du cookie d'actualisation. |
COOKIE_SECURE | true | Obligatoire lorsque l'application est diffusée via HTTPS. |
JWT_SECRET | Secret aléatoire stable, au moins 16 caractères | Signe les sessions utilisateur. La rotation exclut tout le monde. |
MCP_INTERNAL_SECRET | Secret aléatoire stable, d'au moins 32 caractères et différent de JWT_SECRET | Permet aux services MCP et API publics d'échanger des informations d'identification OAuth liées à l'audience sans transférer de jeton MCP vers /api/v1. Les deux services doivent toujours utiliser la même valeur. |
MFA_ENCRYPTION_KEY | Secret aléatoire stable, au moins 32 caractères | Protège l’inscription et les défis des authentificateurs. La rotation invalide les authentifiants inscrits. |
MEDIA_SIGNING_SECRET | Secret aléatoire stable, au moins 32 caractères | Signe les URL des médias privés. La rotation invalide les URL signées existantes. |
SECRETS_ENCRYPTION_KEY | Secret aléatoire stable, d'au moins 32 caractères et différent de JWT_SECRET | Chiffre les informations d'identification SMTP, de stockage, de webhook et d'intégration stockées dans la base de données. |
KANERA_DEPLOYMENT_MODE par défaut self_hosted. Le mode hébergé et ses variables Stripe, PostHog, plan-limit et licence sont destinés aux déploiements opérés par Kanera et doivent rester non définis sur une installation auto-hébergée.
Composer des fournitures NODE_ENV=production et ANALYTICS_ENABLED=false. Partir ANALYTICS_PROVIDER, POSTHOG_PROJECT_KEY, POSTHOG_API_HOST, chaque STRIPE_*, HOSTED_*et le jeton de mode hébergé n'est pas défini. Ces paramètres ne transforment pas une installation auto-hébergée en Kanera Cloud.
URL et services publics
| Variable | Par défaut | Réglez-le quand |
|---|---|---|
KANERA_ENVIRONMENT | production en production Composer | Vous avez besoin d'un préfixe de clé API différent pour le développement, les tests ou la préparation. |
API_PUBLIC_URL | WEB_ORIGIN | L’API de l’application orientée navigateur utilise une origine publique différente. |
KANERA_PUBLIC_API_URL | http://public-api:3001 dans Composer | MCP ou un autre processus interne atteint l'API publique ailleurs que son adresse de service Compose. Il s'agit d'une URL interne, et non de l'origine de l'API orientée navigateur. |
PUBLIC_API_OAUTH_ISSUER | http://localhost:3001 | Vous exposez OAuth ou l'API publique à distance ; utilisez son origine HTTPS accessible par le navigateur. |
MCP_SERVER_PUBLIC_URL | http://localhost:3002/mcp | Vous exposez MCP distant ; utiliser le public complet /mcp URL. |
MCP_PUBLIC_URL | Dérivé de MCP_SERVER_PUBLIC_URL par Composer | Vous exécutez le service MCP en dehors du câblage Compose fourni. |
OAUTH_ISSUER_URL | Dérivé de PUBLIC_API_OAUTH_ISSUER par Composer | Vous exécutez MCP en dehors du câblage Compose fourni. |
API_PORT, PUBLIC_API_PORT, WORKER_PORT, MCP_PORT | 3000, 3001, 3003, 3002 | Vous exécutez des services en dehors de Compose ou avez besoin de différents ports d’écoute internes. |
API_TRUST_PROXY, PUBLIC_API_TRUST_PROXY, MCP_TRUST_PROXY | false, false, true | Un proxy inverse de confiance fournit la véritable adresse IP du client. Ne faites jamais confiance aux en-têtes transmis par des clients arbitraires. |
Le navigateur se connecte à web; ne publiez pas le principal api service. Voir Services et routage avant d'exposer l'API publique ou MCP.
Comptes et authentification
| Variable | Par défaut | Objectif |
|---|---|---|
SIGNUPS_ENABLED | true | Ensemble false pour arrêter l'inscription publique et la création de nouvelles organisations. Les liens d’invitation d’organisation existants fonctionnent toujours. |
EMAIL_VERIFICATION_ENABLED | false | Exigez une vérification des e-mails à six chiffres pour l'inscription, l'inscription sur invitation et les modifications des e-mails. Activer uniquement une fois que SMTP fonctionne. |
AUTH_RATE_LIMIT_ENABLED | true | Activez la limitation par force brute par IP sur les routes d'authentification non authentifiées. |
AUTH_RATE_LIMIT_MAX / AUTH_RATE_LIMIT_WINDOW_MS | 10 / 60000 | Tentatives d'authentification autorisées par fenêtre. |
JWT_ACCESS_TTL / JWT_REFRESH_TTL_DAYS | 5m / 10 | Durées de vie des jetons d’accès et des sessions d’actualisation. |
CLOUDFLARE_TURNSTILE_SITE_KEY / CLOUDFLARE_TURNSTILE_SECRET_KEY | Désarmé | Protection d'inscription hébergée. Laissez-le désactivé pour un auto-hébergement normal. |
Les utilisateurs configurent leur propre authentificateur sous Paramètres -> Votre compte -> Sécurité. Les administrateurs de l'organisation peuvent l'exiger sous Paramètres -> Organisation -> Sécurité. Voir Profil et sécurité.
Limites de l'API publique et du MCP
| Variable | Par défaut | Objectif |
|---|---|---|
PUBLIC_API_RATE_LIMIT_ENABLED | true | Active les limites des requêtes API publiques et MCP. |
PUBLIC_API_IP_RATE_LIMIT_PER_MINUTE | 60 | Limite pour la découverte non authentifiée et les formats de support invalides. |
PUBLIC_API_FAILED_KEY_RATE_LIMIT_PER_MINUTE | 10 | Limite par IP pour les échecs kanera_* tentatives clés. |
PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE | 400 | Limite de requêtes par clé après une authentification réussie. |
PUBLIC_API_UPLOAD_RATE_LIMIT_PER_MINUTE | 30 | Limite de téléchargement de pièces jointes par clé. |
PUBLIC_API_RATE_LIMIT_WINDOW_MS | 60000 | Fenêtre de limite de débit partagée par l'API publique et MCP. |
MCP_BODY_MAX_BYTES | 1048576 | Corps maximal de la requête MCP. |
MCP_REQUEST_TIMEOUT_MS | 30000 | Durée maximale pour une requête MCP. |
MCP_HEADERS_TIMEOUT_MS / MCP_KEEP_ALIVE_TIMEOUT_MS | 10000 / 5000 | Délais d’expiration de la connexion HTTP MCP. |
KANERA_API_KEY | Désarmé | Requis uniquement par le pont MCP stdio local, et non par le service HTTP MCP. |
Base de données, cache et capacité
Composer des fournitures DATABASE_URL et REDIS_URL pour les services groupés PostgreSQL et Valkey. Définissez-les vous-même uniquement lorsque vous exécutez un processus en dehors de ce réseau ou lorsque vous utilisez des services gérés.
| Variable | Composer par défaut | Objectif |
|---|---|---|
DATABASE_SSL | false | Activer uniquement lorsqu'une base de données externe nécessite SSL. |
POSTGRES_BIND_PORT | 5433 | Port hôte de bouclage uniquement pour PostgreSQL fourni. |
API_REPLICAS / PUBLIC_API_REPLICAS / MCP_REPLICAS | 2 / 1 / 1 | Le processus de service compte. Gardez le travailleur à exactement un. |
PG_POOL_MAX / WORKER_PG_POOL_MAX | 20 / 5 | Nombre maximal de connexions à la base de données par processus d'application et pour le travailleur. |
PG_IDLE_TIMEOUT_MS / PG_CONNECTION_TIMEOUT_MS | 30000 / 5000 | Inactivité du pool et délais d’attente d’acquisition. |
PG_STATEMENT_TIMEOUT_MS / SLOW_QUERY_LOG_MS | 30000 / 250 | Délai d’expiration des requêtes de base de données et seuil de journalisation des requêtes lentes. |
NODE_OPTIONS | Désarmé | Indicateurs de nœud facultatifs, tels qu'une limite de tas. |
UV_THREADPOOL_SIZE | 16 | Threads de travail natifs utilisés pour le hachage, le chiffrement et le traitement d'images. |
REALTIME_WEBSOCKET_COMPRESSION_ENABLED | true | Compressez les messages Socket.IO WebSocket plus volumineux. |
REALTIME_WEBSOCKET_COMPRESSION_THRESHOLD_BYTES | 1024 | Taille minimale de l’image en temps réel à compresser. |
REALTIME_OUTBOX_POLL_MS | 500 dans Composer | Intervalle d’interrogation de secours du travailleur pour les lignes de boîte d’envoi en temps réel et webhook. |
USER_DISPLAY_CACHE_TTL_MS | 60000 | Durée de vie du cache en cours pour les recherches de nom d'affichage. |
Regroupez les réplicas et les pools uniquement après avoir mesuré la capacité. Voir Mises à jour et mise à l'échelle.
Stockage de fichiers et d'objets
| Variable | Par défaut | Objectif |
|---|---|---|
UPLOADS_DIR | /data/uploads dans Composer | Répertoire de téléchargement local. Bundled Compose corrige ce chemin et le conserve dans kanera_uploads; modifier le mappage de volume plutôt que .env. |
ATTACHMENT_MAX_BYTES | 104857600 | Taille maximale des pièces jointes téléchargées en octets. |
S3_REGION / S3_BUCKET | Désarmé | Démarrez le stockage compatible S3 à l’échelle du déploiement lorsque les informations d’identification vous sont fournies. |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | Désarmé | Identifiants pour le compartiment de téléchargement. Les deux sont requis pour S3 basé sur l’environnement. |
S3_ENDPOINT | Désarmé | Point de terminaison personnalisé pour MinIO, R2 ou un autre fournisseur compatible S3. Sa définition active les requêtes de style chemin. |
S3_PUBLIC_URL_PREFIX | Désarmé | Préfixe public ou CDN facultatif pour les objets stockés. |
Le stockage de l'environnement est prioritaire sur le stockage de l'organisation configuré dans l'application. Voir Stockage et sauvegardes avant de changer une installation qui a déjà des téléchargements.
E-mail, notifications et intégrations
| Variable | Par défaut | Objectif |
|---|---|---|
SMTP_HOST, SMTP_USER, SMTP_PASSWORD, SMTP_FROM_EMAIL | Désarmé | Connexion SMTP sortante par défaut et expéditeur. |
SMTP_PORT / SMTP_SECURITY | 587 / starttls | Port et transport SMTP : starttls, tls, ou none. |
SMTP_FROM_NAME | Kanera | Nom d’affichage de l’expéditeur. |
SMTP_IDENTITY_DOMAIN | Domaine de messagerie de l'expéditeur | Domaine EHLO et Message-ID. |
INTERNAL_NOTIFICATION_EMAILS | Désarmé | Destinataires séparés par des virgules pour les alertes d'inscription et d'invitation en texte brut. Nécessite un environnement SMTP. |
KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS | false | Autorisez les récepteurs personnels ntfy, Gotify et webhook sur les réseaux HTTP ou privés. Les adresses réservées et de métadonnées restent bloquées. |
ALERT_WEBHOOK_URL | Désarmé | Destination compatible Slack pour les alertes de préparation, d’exécution et Grafana. |
OPS_ALERTS_ENABLED / OPS_ALERT_THROTTLE_MS | true / 300000 | Activez et dupliquez les alertes opérationnelles. Rien n'est envoyé sans destination. |
SLOW_REQUEST_LOG_MS | 2500 | Seuil d’avertissement de demande lente dans les journaux. |
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY | Désarmé | Application GitHub facultative définie par le déploiement pour les aperçus de liens privés. Les administrateurs auto-hébergés peuvent à la place utiliser le flux de manifeste intégré à l'application. |
TRELLO_API_KEY | Désarmé | Permet aux importations Trello d'authentifier et de copier les pièces jointes. |
Voir E-mail et notifications et Intégrations et API.
Sauvegardes et conservation
| Variable | Par défaut | Objectif |
|---|---|---|
DB_BACKUPS_ENABLED | false | Activez les sauvegardes PostgreSQL chiffrées planifiées sur un stockage compatible S3. |
DB_BACKUP_ENCRYPTION_PASSPHRASE | Désarmé | Requis lorsque les sauvegardes sont activées et requis à nouveau pour les restaurer. |
DB_BACKUP_TIMES_UTC | 00:15,12:15,16:45 | Heures de sauvegarde UTC quotidiennes séparées par des virgules. |
DB_BACKUP_RETENTION_DAYS | 14 | Fenêtre de rétention de sauvegarde réussie. |
DB_BACKUP_S3_PREFIX | backups/postgres | Préfixe d'objet pour les sauvegardes de base de données. |
DB_BACKUP_S3_BUCKET, DB_BACKUP_S3_REGION, DB_BACKUP_S3_ENDPOINT | Valeurs de stockage de téléchargement | Destination de sauvegarde séparée facultative. |
DB_BACKUP_S3_ACCESS_KEY_ID, DB_BACKUP_S3_SECRET_ACCESS_KEY | Valeurs de stockage de téléchargement | Informations d'identification de sauvegarde séparées en option. |
ACTIVITY_EVENT_RETENTION_DAYS | 730 | Conservation de l’historique des activités. |
ADMIN_AUDIT_LOG_RETENTION_DAYS | 1095 | Conservation des journaux d’audit de gestion. |
NOTIFICATION_READ_RETENTION_DAYS / NOTIFICATION_MAX_RETENTION_DAYS | 90 / 365 | Notification de lecture et conservation absolue des notifications. |
AUTH_TOKEN_RETENTION_DAYS | 30 | La période de grâce avant la purge des artefacts d’authentification expirés ou consommés. |
REALTIME_OUTBOX_RETENTION_DAYS / OUTBOX_STUCK_RETENTION_DAYS | 30 / 30 | Rétention de la boîte d'envoi traitée et bloquée de manière permanente. |
Voir Stockage et sauvegardes pour les besoins de sauvegarde et la planification de la restauration.
Surveillance
| Variable | Par défaut | Objectif |
|---|---|---|
METRICS_ENABLED | true | Enregistre les points de terminaison des métriques Prometheus. Ils reviennent 404 sans jeton valide. |
METRICS_TOKEN | Désarmé | Jeton du porteur, d'au moins 16 caractères, requis pour le scraping. |
COMPOSE_PROFILES | Désarmé | Inclure monitoring pour démarrer Grafana, Prometheus, Loki, Alloy et les exportateurs ; inclure admin pour le portail de gestion. |
COMPOSE_PROJECT_NAME | kanera | Composez l'identité utilisée par Alloy pour sélectionner les journaux de ce déploiement. Vérifier docker compose ls sur les plateformes gérées. |
GRAFANA_ADMIN_PASSWORD | Désarmé | Obligatoire lorsque le profil de surveillance est activé. |
MONITORING_BIND_IP | 127.0.0.1 | Interface hôte pour Grafana et Prometheus. Utilisez une adresse VPN privée, jamais 0.0.0.0 en production. |
GRAFANA_BIND_PORT / PROMETHEUS_BIND_PORT | 3000 / 9090 | Ports hôtes pour les deux interfaces utilisateur de surveillance. |
PROMETHEUS_RETENTION / PROMETHEUS_RETENTION_SIZE | 30d / 5GB | Plafonds de temps et de disque pour les données Prometheus. |
GRAFANA_ROOT_URL | Désarmé | URL Grafana externe lors de sa diffusion via un proxy. |
POSTGRES_EXPORTER_DSN | Base de données groupée | Remplacer pour un serveur PostgreSQL externe. |
REALTIME_EMIT_METRICS_ENABLED | false | Activez les métriques de charge utile échantillonnées en temps réel. |
REALTIME_EMIT_METRICS_SAMPLE_RATE / REALTIME_EMIT_METRICS_MIN_BYTES | 0.01 / 0 | Échantillonnage de métriques en temps réel et taille minimale de la charge utile. |
Portail de gestion en option
Le portail de gestion est distinct des paramètres du locataire et possède sa propre limite d'authentification. Activez-le uniquement lorsque les opérateurs ont besoin d’une administration inter-organisationnelle ou de sessions de support auditées.
| Variable | Par défaut | Objectif |
|---|---|---|
ADMIN_WEB_ORIGIN | http://localhost:4300 | Origine publique et limite CORS pour la console d'administration. |
ADMIN_API_PORT | 3002 | Port d'écoute de l'API d'administration interne lorsqu'il s'exécute en dehors du câblage fourni. |
ADMIN_COOKIE_DOMAIN | Désarmé | Remplacement du domaine du cookie lorsque le nom d'hôte de l'administrateur est à l'extérieur COOKIE_DOMAIN. |
ADMIN_JWT_SECRET | Désarmé | Obligatoire pour l'API d'administration et doit différer de JWT_SECRET. |
ADMIN_EMAIL / ADMIN_PASSWORD | Désarmé | Amorcez le premier super-administrateur uniquement lorsque la table admin-user est vide. Ils ne réinitialisent pas un compte existant. |
ADMIN_JWT_ACCESS_TTL / ADMIN_JWT_REFRESH_TTL_DAYS | 15m / 7 | Accès administrateur et durées de vie d’actualisation. |
ADMIN_LOGIN_RATE_LIMIT_MAX / ADMIN_LOGIN_RATE_LIMIT_WINDOW_MS | 5 / 300000 | Accélérateur de connexion administrateur par IP. |
ADMIN_TRUST_PROXY | true | Faites confiance au proxy inverse de l'administrateur pour les adresses IP réelles des clients. |
SUPPORT_SESSION_TTL_MINUTES | 60 | Durée de vie d'une session d'assistance de courte durée ; maximum huit heures et aucun jeton d’actualisation. |
Gardez le portail de gestion privé, utilisez un nom d'hôte et un secret distincts et consultez son journal d'audit. Le câblage complet du déploiement est documenté dans DEPLOY.md dans le référentiel Kanera.
Appliquer et vérifier les modifications
La plupart des modifications nécessitent de recréer les services concernés :
docker compose config --quiet
docker compose up -d
docker compose ps
Vérifiez les journaux de service pertinents après avoir modifié les paramètres d'authentification, de livraison, de stockage, d'API, MCP ou d'administration. Un syntaxiquement valide .env ne prouve pas que les informations d'identification externes ou les URL fonctionnent.