Configurer votre instance

Tout ce qui concerne votre instance se configure via le fichier .env que vous avez créé lors de l'installation. Cette page passe en revue les paramètres qu'un opérateur manipule réellement, regroupés selon leur fonction, plutôt que de lister chaque variable présente dans le modèle.

Après avoir modifié .env, appliquez le changement en recréant les conteneurs :

docker compose up -d

Identité et URL

• APP_NAME est le nom affiché dans l'interface et dans les e-mails. Sa valeur par défaut est Kollek.
• APP_URL est l'adresse publique de votre instance. Les liens dans les e-mails sont construits à partir de cette valeur, elle doit donc correspondre à l'adresse réellement utilisée par vos utilisateurs.
• APP_PORT est le port de l'hôte publié par le conteneur web, 8000 par défaut.

La clé d'application

APP_KEY chiffre les données sensibles au repos. Vous la définissez une fois lors de l'installation et ne la changez jamais à la légère. Elle est suffisamment importante pour avoir sa propre page, qui traite aussi du mécanisme de rotation APP_PREVIOUS_KEYS.

Base de données

DB_DATABASE, DB_USERNAME, DB_PASSWORD et DB_ROOT_PASSWORD configurent le conteneur MySQL fourni. Changez les deux mots de passe par rapport à leurs valeurs de remplacement avant le premier démarrage. RUN_MIGRATIONS contrôle si le conteneur web migre au démarrage (true par défaut).

E-mail

MAIL_MAILER détermine comment les e-mails quittent votre instance, et sa valeur par défaut est log.

Stockage des fichiers

FILESYSTEM_DISK vaut local par défaut : les photos et documents téléversés sont stockés dans le volume storage-data. Pour utiliser à la place un stockage objet compatible S3, définissez cette valeur à s3 et renseignez les variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET et, pour les fournisseurs autres qu'AWS, AWS_ENDPOINT. Les fichiers sont servis aux utilisateurs via des routes privées vérifiées par compte, quel que soit le cas, jamais comme des URL publiques.

Entretien courant

• TRASH_RETENTION_DAYS définit combien de temps les objets supprimés en douceur restent dans la corbeille avant que la purge nocturne ne les supprime définitivement. La valeur par défaut est de 30 jours.
• ACCOUNT_DELETION_NOTIFICATION_EMAIL est l'adresse notifiée lorsqu'un utilisateur supprime son propre utilisateur ou est retiré par le nettoyage d'inactivité. Faites-la pointer vers vous-même afin qu'aucun départ ne passe inaperçu.

Le site vitrine public

SHOW_MARKETING_SITE vaut false par défaut, ce qui signifie que votre instance ne sert que l'application elle-même. Définissez cette valeur à true pour servir aussi les pages vitrine publiques et la référence API générée à /docs/api. La plupart des instances privées laissent ce réglage désactivé ; activez-le si vos développeurs souhaitent que la référence API soit servie localement.

Ces pages sont les mêmes pour tous les visiteurs et ne changent qu'au redéploiement, donc chacune part avec des en-têtes de cache : un navigateur la garde cinq minutes, et tout CDN placé devant l'instance la garde une semaine. Définissez CACHE_PUBLIC_PAGES à false pour ne plus les envoyer. Dans les deux cas, rien n'est mis en cache sur l'instance elle-même.

Si vous servez le site à travers Cloudflare, renseignez aussi CLOUDFLARE_API_TOKEN et CLOUDFLARE_ZONE_ID. Ce sont eux qui permettent à l'instance de demander à Cloudflare de supprimer ce qu'il conserve quand quelque chose d'affiché sur le site public change, d'elle même ou depuis le panneau. Laissez-les vides sur une instance servie directement : il n'y a rien à purger devant elle.

Dans les deux cas, l'instance répond elle-même à /robots.txt au lieu de servir un fichier présent sur le disque. Quand le site public est activé, elle oriente les robots vers /sitemap.xml, qui liste toutes les pages publiques dans chacune des langues où elles existent. Quand il est désactivé, elle demande à tous les robots de rester en dehors de l'hôte entier, car une instance privée n'a rien qui mérite d'être indexé.

Protection contre le spam

Rien n'empêche un robot de remplir votre formulaire d'inscription, et sur une instance accessible à tous cela finit toujours par arriver. TURNSTILE_ENABLED place un widget Cloudflare Turnstile sur les formulaires de connexion, d'inscription et de réinitialisation du mot de passe, de sorte qu'un envoi qui ne l'a pas résolu n'atteint jamais l'application.

Ce réglage vaut false par défaut, ce qui est la bonne réponse pour une instance privée où vous connaissez toutes les personnes qui se connectent. Pour l'activer, créez un widget Turnstile dans votre compte Cloudflare, puis définissez TURNSTILE_ENABLED à true, TURNSTILE_SITE_KEY avec la clé publique qu'il vous donne et TURNSTILE_SECRET_KEY avec la clé privée. Le réglage seul ne protège rien : sans les deux clés, aucun visiteur ne peut passer la vérification.

Ce que vous n'avez pas besoin de configurer

Les sessions (SESSION_DRIVER), le cache (CACHE_STORE) et la file d'attente (QUEUE_CONNECTION) reposent tous sur database par défaut. Les valeurs par défaut sont correctes pour la stack fournie, et il n'y a pas de Redis ni d'autre service à ajouter. Laissez-les inchangées à moins de savoir précisément pourquoi vous les modifiez.

Et ensuite

• Faites circuler de vrais e-mails dans Configurer la livraison des e-mails.
• Comprenez la clé que vous devez protéger dans La clé d'application et le chiffrement.
• Mettez en place les sauvegardes.