Referentie voor zelfgehoste omgevingen
Begin met de release env.example, die je hebt gedownload als .env binnen Aan de slag. Het is de kleinste ondersteunde Compose-configuratie. Gebruik env.full.example wanneer u een optionele instelling nodig heeft; op deze pagina wordt uitgelegd welke instellingen bij elkaar horen en wanneer u deze kunt wijzigen.
Na bewerking .envvalideert u de interpolatie zonder de opgeloste configuratie af te drukken:
docker compose config --quiet
Niet plegen .env, plak het in ondersteuningsverzoeken of geef de uitvoer vrij van docker compose config: de opgeloste uitvoer bevat geheimen.
Vereiste productiewaarden
Genereer elk geheim onafhankelijk met openssl rand -hex 32. Behoud de oude waarden bij elke upgrade en bewaar een herstelkopie buiten de server.
| Variabel | Productiewaarde | Waarom het ertoe doet |
|---|---|---|
POSTGRES_PASSWORD | Uniek willekeurig wachtwoord | Beschermt de gebundelde PostgreSQL-database. |
WEB_ORIGIN | Openbare HTTPS-app-oorsprong, zoals https://kanera.example.com | Wordt gebruikt voor browserlinks, CORS en authenticatiestromen. Voeg geen afsluitende schuine streep toe. |
COOKIE_DOMAIN | App-hostnaam, zoals kanera.example.com | Reikwijdte voor de vernieuwingscookie. |
COOKIE_SECURE | true | Vereist wanneer de app via HTTPS wordt aangeboden. |
JWT_SECRET | Stabiel willekeurig geheim, minimaal 16 tekens | Ondertekent gebruikerssessies. Rotatie meldt iedereen af. |
MCP_INTERNAL_SECRET | Stabiel willekeurig geheim, minimaal 32 tekens en verschillend van JWT_SECRET | Hiermee kunnen de MCP- en openbare API-services doelgroepgebonden OAuth-inloggegevens uitwisselen zonder een MCP-token door te sturen /api/v1. Beide services moeten altijd dezelfde waarde gebruiken. |
MFA_ENCRYPTION_KEY | Stabiel willekeurig geheim, minimaal 32 tekens | Beschermt authenticatorinschrijving en uitdagingen. Rotatie maakt ingeschreven authenticators ongeldig. |
MEDIA_SIGNING_SECRET | Stabiel willekeurig geheim, minimaal 32 tekens | Ondertekent privémedia-URL's. Rotatie maakt bestaande ondertekende URL's ongeldig. |
SECRETS_ENCRYPTION_KEY | Stabiel willekeurig geheim, minimaal 32 tekens en verschillend van JWT_SECRET | Versleutelt SMTP-, opslag-, webhook- en integratiereferenties die zijn opgeslagen in de database. |
KANERA_DEPLOYMENT_MODE standaard ingesteld op self_hosted. De gehoste modus en de bijbehorende Stripe-, PostHog-, plan-limit- en licentievariabelen zijn bedoeld voor door Kanera beheerde implementaties en moeten uitgeschakeld blijven op een zelf-gehoste installatie.
Benodigdheden samenstellen NODE_ENV=production en ANALYTICS_ENABLED=false. Vertrekken ANALYTICS_PROVIDER, POSTHOG_PROJECT_KEY, POSTHOG_API_HOST, elke STRIPE_*, HOSTED_*en het token in de gehoste modus is uitgeschakeld. Deze instellingen veranderen een zelf-gehoste installatie niet in Kanera Cloud.
Openbare URL's en services
| Variabel | Standaard | Stel in wanneer |
|---|---|---|
KANERA_ENVIRONMENT | production in productie Componeren | U hebt een ander API-sleutelvoorvoegsel nodig voor ontwikkeling, testen of staging. |
API_PUBLIC_URL | WEB_ORIGIN | De browsergerichte app-API gebruikt een andere openbare oorsprong. |
KANERA_PUBLIC_API_URL | http://public-api:3001 bij Componeren | MCP of een ander intern proces bereikt de openbare API ergens anders dan het Compose-serviceadres. Dit is een interne URL, niet de browsergerichte API-oorsprong. |
PUBLIC_API_OAUTH_ISSUER | http://localhost:3001 | U maakt OAuth of de openbare API op afstand openbaar; gebruik de browser-bereikbare HTTPS-oorsprong. |
MCP_SERVER_PUBLIC_URL | http://localhost:3002/mcp | Je stelt externe MCP bloot; gebruik maken van het volledige publiek /mcp URL. |
MCP_PUBLIC_URL | Afgeleid van MCP_SERVER_PUBLIC_URL door Componeren | Je voert de MCP-service uit buiten de meegeleverde Compose-bedrading. |
OAUTH_ISSUER_URL | Afgeleid van PUBLIC_API_OAUTH_ISSUER door Componeren | Je gebruikt de MCP buiten de meegeleverde Compose-bedrading. |
API_PORT, PUBLIC_API_PORT, WORKER_PORT, MCP_PORT | 3000, 3001, 3003, 3002 | U voert services buiten Compose uit of hebt verschillende interne luisteraarpoorten nodig. |
API_TRUST_PROXY, PUBLIC_API_TRUST_PROXY, MCP_TRUST_PROXY | false, false, true | Een vertrouwde reverse proxy levert het echte client-IP. Vertrouw nooit doorgestuurde headers van willekeurige clients. |
De browser maakt verbinding met web; publiceer de belangrijkste niet api dienst. Zie Diensten en routering voordat het publiek API of MCP wordt blootgesteld.
Accounts en authenticatie
| Variabel | Standaard | Doel |
|---|---|---|
SIGNUPS_ENABLED | true | Instellen false om openbare aanmelding en het creëren van nieuwe organisaties te stoppen. Bestaande uitnodigingslinks voor organisaties werken nog steeds. |
EMAIL_VERIFICATION_ENABLED | false | Een zescijferige e-mailcontrole vereisen voor aanmelding, aanmelding voor uitnodigingen en e-mailwijzigingen. Alleen inschakelen nadat SMTP werkt. |
AUTH_RATE_LIMIT_ENABLED | true | Schakel de brute-force-beperking per IP in op niet-geverifieerde verificatieroutes. |
AUTH_RATE_LIMIT_MAX / AUTH_RATE_LIMIT_WINDOW_MS | 10 / 60000 | Toegestane authentificatiepogingen per venster. |
JWT_ACCESS_TTL / JWT_REFRESH_TTL_DAYS | 5m / 10 | Levensduur van toegangstokens en vernieuwingssessies. |
CLOUDFLARE_TURNSTILE_SITE_KEY / CLOUDFLARE_TURNSTILE_SECRET_KEY | Uitgeschakeld | Gehoste aanmeldingsbescherming. Laat deze instelling uitgeschakeld voor normale zelfhosting. |
Gebruikers configureren hun eigen authenticator onder Instellingen -> Uw account -> Beveiliging. Organisatiebeheerders kunnen dit vereisen onder Instellingen -> Organisatie -> Beveiliging. Zie Profiel en beveiliging.
Openbare API- en MCP-limieten
| Variabel | Standaard | Doel |
|---|---|---|
PUBLIC_API_RATE_LIMIT_ENABLED | true | Schakelt openbare API- en MCP-verzoeklimieten in. |
PUBLIC_API_IP_RATE_LIMIT_PER_MINUTE | 60 | Limiet voor niet-geverifieerde detectie en ongeldige dragerformaten. |
PUBLIC_API_FAILED_KEY_RATE_LIMIT_PER_MINUTE | 10 | Limiet per IP voor mislukt kanera_* belangrijke pogingen. |
PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE | 400 | Verzoeklimiet per sleutel na succesvolle authenticatie. |
PUBLIC_API_UPLOAD_RATE_LIMIT_PER_MINUTE | 30 | Limiet voor het uploaden van bijlagen per sleutel. |
PUBLIC_API_RATE_LIMIT_WINDOW_MS | 60000 | Tarieflimietvenster gedeeld door de openbare API en MCP. |
MCP_BODY_MAX_BYTES | 1048576 | Maximale MCP-aanvraagtekst. |
MCP_REQUEST_TIMEOUT_MS | 30000 | Maximale tijd voor een MCP-aanvraag. |
MCP_HEADERS_TIMEOUT_MS / MCP_KEEP_ALIVE_TIMEOUT_MS | 10000 / 5000 | MCP HTTP-verbindingstime-outs. |
KANERA_API_KEY | Uitgeschakeld | Alleen vereist door de lokale stdio MCP-bridge, niet de HTTP MCP-service. |
Database, cache en capaciteit
Benodigdheden samenstellen DATABASE_URL en REDIS_URL voor de gebundelde PostgreSQL- en Valkey-services. Stel ze alleen zelf in als u een proces buiten dat netwerk uitvoert of beheerde services gebruikt.
| Variabel | Stel standaard samen | Doel |
|---|---|---|
DATABASE_SSL | false | Alleen inschakelen als een externe database SSL vereist. |
POSTGRES_BIND_PORT | 5433 | Alleen-loopback-hostpoort voor gebundelde PostgreSQL. |
API_REPLICAS / PUBLIC_API_REPLICAS / MCP_REPLICAS | 2 / 1 / 1 | Serviceproces telt. Houd de werker op precies één. |
PG_POOL_MAX / WORKER_PG_POOL_MAX | 20 / 5 | Maximale databaseverbindingen per app-proces en voor de werknemer. |
PG_IDLE_TIMEOUT_MS / PG_CONNECTION_TIMEOUT_MS | 30000 / 5000 | Pool-inactiviteit en acquisitie-time-outs. |
PG_STATEMENT_TIMEOUT_MS / SLOW_QUERY_LOG_MS | 30000 / 250 | Time-out voor databasequery's en drempelwaarde voor loggen van langzame query's. |
NODE_OPTIONS | Uitgeschakeld | Optionele knooppuntvlaggen, zoals een heaplimiet. |
UV_THREADPOOL_SIZE | 16 | Native worker-threads die worden gebruikt door hashing, crypto en beeldverwerking. |
REALTIME_WEBSOCKET_COMPRESSION_ENABLED | true | Comprimeer grotere Socket.IO WebSocket-berichten. |
REALTIME_WEBSOCKET_COMPRESSION_THRESHOLD_BYTES | 1024 | Minimale realtime framegrootte om te comprimeren. |
REALTIME_OUTBOX_POLL_MS | 500 bij Componeren | Polling-interval voor fallback van werknemers voor realtime- en webhook-outbox-rijen. |
USER_DISPLAY_CACHE_TTL_MS | 60000 | Levensduur van de cache tijdens het proces voor het opzoeken van weergavenamen. |
Breng replica's en pools pas samen na het meten van de capaciteit. Zie Updates en schaling.
Bestanden en objectopslag
| Variabel | Standaard | Doel |
|---|---|---|
UPLOADS_DIR | /data/uploads bij Componeren | Lokale uploadmap. Bundled Compose repareert dit pad en zet het voort kanera_uploads; verander de volumetoewijzing in plaats van .env. |
ATTACHMENT_MAX_BYTES | 104857600 | Maximale grootte van geüploade bijlagen in bytes. |
S3_REGION / S3_BUCKET | Uitgeschakeld | Start implementatiebrede S3-compatibele opslag wanneer u beschikt over inloggegevens. |
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY | Uitgeschakeld | Inloggegevens voor de uploadbucket. Beide zijn vereist voor omgevingsgebaseerde S3. |
S3_ENDPOINT | Uitgeschakeld | Aangepast eindpunt voor MinIO, R2 of een andere S3-compatibele provider. Als u dit instelt, worden verzoeken in padstijl ingeschakeld. |
S3_PUBLIC_URL_PREFIX | Uitgeschakeld | Optioneel openbaar of CDN-voorvoegsel voor opgeslagen objecten. |
Omgevingsopslag heeft voorrang op organisatieopslag die in de app is geconfigureerd. Zie Opslag en back-ups voordat u overschakelt naar een installatie die al uploads heeft.
E-mail, meldingen en integraties
| Variabel | Standaard | Doel |
|---|---|---|
SMTP_HOST, SMTP_USER, SMTP_PASSWORD, SMTP_FROM_EMAIL | Uitgeschakeld | Standaard uitgaande SMTP-verbinding en afzender. |
SMTP_PORT / SMTP_SECURITY | 587 / starttls | SMTP-poort en transport: starttls, tls, of none. |
SMTP_FROM_NAME | Kanera | Weergavenaam van afzender. |
SMTP_IDENTITY_DOMAIN | E-maildomein van afzender | EHLO- en Message-ID-domein. |
INTERNAL_NOTIFICATION_EMAILS | Uitgeschakeld | Door komma's gescheiden ontvangers voor aanmelding in platte tekst en uitnodigingswaarschuwingen. Vereist omgevings-SMTP. |
KANERA_ALLOW_PRIVATE_NOTIFICATION_DESTINATIONS | false | Sta persoonlijke ntfy-, Gotify- en webhook-ontvangers toe op HTTP- of privénetwerken. Gereserveerde en metadata-adressen blijven geblokkeerd. |
ALERT_WEBHOOK_URL | Uitgeschakeld | Slack-compatibele bestemming voor gereedheids-, runtime- en Grafana-waarschuwingen. |
OPS_ALERTS_ENABLED / OPS_ALERT_THROTTLE_MS | true / 300000 | Schakel operationele waarschuwingen in en ontdubbel ze. Niets wordt zonder bestemming verzonden. |
SLOW_REQUEST_LOG_MS | 2500 | Drempel voor een waarschuwing voor langzame aanvragen in logboeken. |
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEY | Uitgeschakeld | Optionele, door de implementatie gedefinieerde GitHub-app voor previews van privékoppelingen. Zelf-hostende beheerders kunnen in plaats daarvan de in-app-manifeststroom gebruiken. |
TRELLO_API_KEY | Uitgeschakeld | Laat Trello importeert bijlagen verifiëren en kopiëren. |
Zie E-mail en meldingen en Integraties en API's.
Back-ups en retentie
| Variabel | Standaard | Doel |
|---|---|---|
DB_BACKUPS_ENABLED | false | Schakel geplande gecodeerde PostgreSQL-back-ups naar S3-compatibele opslag in. |
DB_BACKUP_ENCRYPTION_PASSPHRASE | Uitgeschakeld | Vereist wanneer back-ups zijn ingeschakeld en opnieuw vereist om ze te herstellen. |
DB_BACKUP_TIMES_UTC | 00:15,12:15,16:45 | Door komma's gescheiden dagelijkse UTC-back-uptijden. |
DB_BACKUP_RETENTION_DAYS | 14 | Succesvolle bewaarperiode voor back-ups. |
DB_BACKUP_S3_PREFIX | backups/postgres | Objectvoorvoegsel voor databasedumps. |
DB_BACKUP_S3_BUCKET, DB_BACKUP_S3_REGION, DB_BACKUP_S3_ENDPOINT | Upload-opslagwaarden | Optioneel afzonderlijk back-updoel. |
DB_BACKUP_S3_ACCESS_KEY_ID, DB_BACKUP_S3_SECRET_ACCESS_KEY | Upload-opslagwaarden | Optionele afzonderlijke back-upreferenties. |
ACTIVITY_EVENT_RETENTION_DAYS | 730 | Behouden van activiteitengeschiedenis. |
ADMIN_AUDIT_LOG_RETENTION_DAYS | 1095 | Bewaren van beheerauditlogboeken. |
NOTIFICATION_READ_RETENTION_DAYS / NOTIFICATION_MAX_RETENTION_DAYS | 90 / 365 | Leesmelding en absoluut behoud van meldingen. |
AUTH_TOKEN_RETENTION_DAYS | 30 | De respijtperiode voordat verlopen of verbruikte auth-artefacten worden verwijderd. |
REALTIME_OUTBOX_RETENTION_DAYS / OUTBOX_STUCK_RETENTION_DAYS | 30 / 30 | Verwerkte en permanent vastgelopen outbox-retentie. |
Zie Opslag en back-ups voor back-upvereisten en herstelplanning.
Toezicht
| Variabel | Standaard | Doel |
|---|---|---|
METRICS_ENABLED | true | Registreert eindpunten van Prometheus-metrieken. Ze keren terug 404 zonder geldig token. |
METRICS_TOKEN | Uitgeschakeld | Bearer-token, minimaal 16 tekens, vereist voor scrapen. |
COMPOSE_PROFILES | Uitgeschakeld | Inclusief monitoring om Grafana, Prometheus, Loki, Alloy en exporteurs te starten; omvatten admin voor het beheerportaal. |
COMPOSE_PROJECT_NAME | kanera | Stel de identiteit samen die door Alloy wordt gebruikt om de logboeken van deze implementatie te selecteren. Controleer docker compose ls op beheerde platforms. |
GRAFANA_ADMIN_PASSWORD | Uitgeschakeld | Vereist wanneer het monitoringprofiel is ingeschakeld. |
MONITORING_BIND_IP | 127.0.0.1 | Hostinterface voor Grafana en Prometheus. Gebruik nooit een privé VPN-adres 0.0.0.0 in productie. |
GRAFANA_BIND_PORT / PROMETHEUS_BIND_PORT | 3000 / 9090 | Hostpoorten voor de twee monitoring-UI's. |
PROMETHEUS_RETENTION / PROMETHEUS_RETENTION_SIZE | 30d / 5GB | Tijd- en schijfplafonds voor Prometheus-gegevens. |
GRAFANA_ROOT_URL | Uitgeschakeld | Externe Grafana-URL bij weergave via een proxy. |
POSTGRES_EXPORTER_DSN | Gebundelde database | Overschrijven voor een externe PostgreSQL-server. |
REALTIME_EMIT_METRICS_ENABLED | false | Schakel bemonsterde realtime payload-statistieken in. |
REALTIME_EMIT_METRICS_SAMPLE_RATE / REALTIME_EMIT_METRICS_MIN_BYTES | 0.01 / 0 | Realtime bemonstering van metrische gegevens en minimale payloadgrootte. |
Optioneel beheerportaal
De beheerportal staat los van de tenantinstellingen en heeft een eigen authenticatiegrens. Schakel het alleen in als operators organisatiebreed beheer of gecontroleerde ondersteuningssessies nodig hebben.
| Variabel | Standaard | Doel |
|---|---|---|
ADMIN_WEB_ORIGIN | http://localhost:4300 | Openbare oorsprong en CORS-grens voor de beheerdersconsole. |
ADMIN_API_PORT | 3002 | Interne beheer-API-listenerpoort wanneer deze buiten de gebundelde bedrading wordt uitgevoerd. |
ADMIN_COOKIE_DOMAIN | Uitgeschakeld | Cookie-domein overschrijven wanneer de hostnaam van de beheerder zich buiten bevindt COOKIE_DOMAIN. |
ADMIN_JWT_SECRET | Uitgeschakeld | Vereist voor de admin API en moet afwijken van JWT_SECRET. |
ADMIN_EMAIL / ADMIN_PASSWORD | Uitgeschakeld | Seed de eerste superadmin alleen als de admin-user-tabel leeg is. Ze resetten geen bestaand account. |
ADMIN_JWT_ACCESS_TTL / ADMIN_JWT_REFRESH_TTL_DAYS | 15m / 7 | Beheerderstoegang en vernieuwingslevensduren. |
ADMIN_LOGIN_RATE_LIMIT_MAX / ADMIN_LOGIN_RATE_LIMIT_WINDOW_MS | 5 / 300000 | Inlogbeperking per IP-beheerder. |
ADMIN_TRUST_PROXY | true | Vertrouw op de omgekeerde proxy van de beheerder voor echte client-IP's. |
SUPPORT_SESSION_TTL_MINUTES | 60 | Korte levensduur van de ondersteuningssessie; maximaal acht uur en geen vernieuwingstoken. |
Houd de beheerportal privé, gebruik een aparte hostnaam en geheim, en bekijk het auditlogboek. De volledige implementatiebedrading is gedocumenteerd in DEPLOY.md in de Kanera-repository.
Wijzigingen toepassen en verifiëren
Bij de meeste wijzigingen moeten de betreffende services opnieuw worden gemaakt:
docker compose config --quiet
docker compose up -d
docker compose ps
Controleer de relevante servicelogboeken na het wijzigen van authenticatie-, leverings-, opslag-, API-, MCP- of beheerdersinstellingen. Een syntactisch geldige .env bewijst niet dat externe inloggegevens of URL's werken.