インスタンスを設定する — ドキュメント

インスタンスに関するすべての設定は、インストールの際に作成した.envファイルを通じて行います。このページでは、テンプレートに含まれるすべての変数を羅列するのではなく、運用者が実際に触れる設定を、その役割ごとにまとめて説明します。

.envを変更したら、コンテナを再作成して反映させます。

docker compose up -d

名前とURL

APP_NAMEは、インターフェースやメールに表示される名前です。デフォルトはKollekです。
APP_URLは、インスタンスの公開アドレスです。メール内のリンクはこの値から生成されるため、ユーザーが実際に使うアドレスに設定する必要があります。
APP_PORTは、webコンテナが公開するホスト側のポートで、デフォルトは8000です。

アプリケーションキー

APP_KEYは、保存されている機密データを暗号化します。インストール時に一度だけ設定し、軽い気持ちで変更してはいけません。これは専用のページを設けるほど重要な項目で、そのページではAPP_PREVIOUS_KEYSによるローテーションの仕組みについても説明しています。

データベース

DB_DATABASE、DB_USERNAME、DB_PASSWORD、DB_ROOT_PASSWORDは、同梱のMySQLコンテナを設定します。初回起動前に、両方のパスワードをプレースホルダーの値から変更してください。RUN_MIGRATIONSは、webコンテナが起動時にマイグレーションを実行するかどうかを制御します(デフォルトはtrue)。

メール

MAIL_MAILERは、インスタンスからメールをどう送信するかを決めるもので、デフォルトはlogです。

メモ

デフォルトのlogメーラーでは、メールは一切送信されません。招待、マジックリンク、パスワードリセット、セキュリティ通知は、代わりにアプリケーションログに書き込まれます。実際のメーラーを設定することは、ほぼすべてのインスタンスで必要になる、唯一と言ってよい設定作業です。メール配信を設定するを参照してください。

ファイルストレージ

FILESYSTEM_DISKのデフォルトはlocalで、アップロードされた写真や書類はstorage-dataボリュームに保存されます。代わりにS3互換のオブジェクトストレージを使うには、s3に設定し、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_DEFAULT_REGION、AWS_BUCKET、そしてAWS以外のプロバイダーの場合はAWS_ENDPOINTの各変数を設定します。どちらの場合も、ファイルは公開URLとしてではなく、アカウントによる確認を伴う非公開のルートを通じてユーザーに提供されます。

日常のメンテナンス設定

TRASH_RETENTION_DAYSは、ソフトデリートされたオブジェクトがゴミ箱に残り、夜間の完全削除処理で消されるまでの日数です。デフォルトは30日です。
ACCOUNT_DELETION_NOTIFICATION_EMAILは、ユーザーが自分自身のユーザーを削除したとき、または非アクティブユーザーの整理によって削除されたときに通知するアドレスです。離脱に気づけるよう、自分自身のアドレスを設定しておきましょう。

公開マーケティングサイト

SHOW_MARKETING_SITEのデフォルトはfalseで、インスタンスはアプリケーション本体のみを提供します。trueに設定すると、公開マーケティングページと、/docs/apiで生成されるAPIリファレンスも提供されます。ほとんどの非公開インスタンスではオフのままにしますが、開発者がAPIリファレンスをローカルで見られるようにしたい場合はオンにしてください。

これらのページはどの訪問者にも同じ内容で、再デプロイしたときにしか変わりません。そのため各ページはキャッシュヘッダー付きで送られます。ブラウザは5分間、インスタンスの前段にあるCDNは1週間そのページを保持します。送信をやめるにはCACHE_PUBLIC_PAGESをfalseにしてください。いずれの場合も、インスタンス自体には何もキャッシュされません。

Cloudflare経由でサイトを配信している場合は、CLOUDFLARE_API_TOKENとCLOUDFLARE_ZONE_IDも設定してください。公開サイトが表示する内容が変わったときに、インスタンス自身から、あるいはパネルから、保持しているものを破棄するようCloudflareへ伝えられるようになります。直接配信しているインスタンスでは空のままにしてください。前段に消すものがありません。

どちらの設定でも、インスタンスはディスク上のファイルを返すのではなく、/robots.txt を自分で応答します。公開サイトが有効なときは、クローラーを /sitemap.xml に案内します。これは公開されているすべてのページを、提供されている言語ごとに並べたものです。公開サイトが無効なときは、すべてのクローラーにホスト全体へ立ち入らないよう伝えます。プライベートなインスタンスには、索引に値するものが何もないからです。

スパム対策

ボットが登録フォームを送信するのを止めるものは何もなく、誰でも到達できるインスタンスでは遅かれ早かれそうなります。TURNSTILE_ENABLEDを有効にすると、ログイン、登録、パスワード再設定の各フォームにCloudflare Turnstileのウィジェットが表示され、それを解いていない送信はアプリケーションまで届かなくなります。

デフォルトはfalseです。ログインする人を全員把握している非公開インスタンスでは、それが正しい設定です。有効にするには、Cloudflareのアカウントでturnstileウィジェットを作成し、TURNSTILE_ENABLEDをtrueに、TURNSTILE_SITE_KEYに発行された公開キーを、TURNSTILE_SECRET_KEYに秘密キーを設定してください。フラグだけでは何も守れません。両方のキーがなければ、どの訪問者も検証を通過できません。

メモ

ウィジェットを有効にすると、インスタンスは送信のたびにCloudflareへ問い合わせます。そのため、誰かがログインするにはchallenges.cloudflare.comに到達できる必要があります。実行できなかった検証は、意図的に、失敗した検証として扱われます。外向きのインターネット接続が安定しないインスタンスでは、この設定はオフのままにしてください。

設定不要なもの

セッション(SESSION_DRIVER)、キャッシュ(CACHE_STORE)、キュー(QUEUE_CONNECTION)は、すべて標準でdatabaseに保存されます。提供されているスタックにはこのデフォルトで問題なく、Redisなどの追加サービスを加える必要もありません。変更する理由を正確に把握していない限り、これらはそのままにしておいてください。

次に読むべきもの

メール配信を設定するで、実際にメールが届くようにしましょう。
アプリケーションキーと暗号化で、保護すべきキーについて理解しましょう。
バックアップを用意しましょう。