チュートリアル: DockerでKolleKをセルフホストする

このチュートリアルでは、何もない状態のマシンから、稼働するKolleKインスタンスまでを作り上げます。プロジェクトをクローンし、環境を設定し、アプリケーションキーを生成し、スタックを起動し、最初のアカウントを作成し、最初のインスタンス管理者を付与します。最後には、実際に動くインスタンスが手に入り、より詳しい運用ガイドがどこから始まるかもわかるようになります。

自宅の小さなサーバーで、コレクタークラブ向けのインスタンスを立ち上げようとしているAlexに沿って進めます。手順は、VPSでもノートパソコンでも同じです。

所要時間の目安は15分から30分で、そのほとんどは最初のビルドを待つ時間です。

始める前に

必要なもの:

• Docker Engine 24以降とComposeプラグイン(古いdocker-composeではなくdocker composeコマンド)が動くマシン。
• プロジェクトをクローンするためのGit。
• ターミナルと、そこで基本的なコマンドを実行できる程度の慣れ。

先にセルフホスティング概要にざっと目を通しておくのもおすすめです。このチュートリアルが繰り返し強調する唯一のルール、アプリケーションキーは一度だけ設定し、絶対に変更しないという点が説明されているためです。

ステップ1: プロジェクトをクローンし、設定ファイルを作成する

git clone https://github.com/djaiss/kollek.git kollek
cd kollek
cp .env.docker.example .env

.envファイルは、あなたのインスタンスの設定そのものです。運用者が日常的に触れるものはすべてここにあり、設定ガイドではグループごとに詳しく説明しています。最初の起動には、次の2つの手順だけが必須です。

ステップ2: アプリケーションキーを生成する

KolleKは、一度だけ生成するキーを使って、機密データを保存時に暗号化します。

docker compose run --rm app php artisan key:generate --show

出力された値(base64:で始まります)をコピーし、.envのAPP_KEYの値として貼り付けます。

意図的なキーローテーションがどうサポートされているかを含む詳しい説明はアプリケーションキーと暗号化にあります。

ステップ3: パスワードとURLを確認する

エディタで.envを開き、次の3点を確認します。

• DB_PASSWORDとDB_ROOT_PASSWORD。 どちらもプレースホルダーの値で出荷されています。最初の起動の前に、自分で決めた強力なパスワードに変更してください。データベースはこれらの値を使って最初の起動時に作成されるためです。
• APP_URL。 ユーザーが入力するアドレスです。Alexはクラブのネットワーク用にhttp://server.local:8000を設定します。デフォルトはhttp://localhost:8000です。
• APP_PORT。 公開されるポートで、変更しなければ8000です。

ステップ4: スタックを起動する

docker compose up -d --build

最初の実行ではイメージのビルドが行われ、数分かかります。その後、Composeは4つのコンテナを起動します。

• app、Webサーバー。データベースマイグレーションを実行するのはこの役割だけで、スキーマはちょうど一度だけセットアップされます。
• queue、メール送信やジョブ処理を行うバックグラウンドワーカー。
• scheduler、日次のメンテナンスジョブを実行します。
• mysql、データベース。

docker compose psで、すべてが起動しているか確認します。appコンテナがhealthyと表示されたら、ブラウザでAPP_URLを開いてください。KolleKのサインイン画面が表示されるはずです。

ステップ5: 最初のアカウントを作成する

登録ページに行き、サインアップします。これはどのユーザーの場合とも全く同じで、手順はアカウントを作成するにあります。これにより、あなたはインスタンス最初のアカウントのオーナーになります。

Alexは登録し、はじめにチェックリストにたどり着きますが、運用作業が終わるまでは何もカタログ化せずにこらえます。

ステップ6: 最初のインスタンス管理者を付与する

インスタンス管理者は、インスタンス管理パネルから、インスタンス上のすべてのアカウントを横断的に見ることができます。このフラグはコマンドラインから付与します。

docker compose exec app php artisan kollek:make-instance-administrator you@example.com

先ほど登録したメールアドレスを使います。同じコマンドに--revokeを付けると、フラグを取り消せます。このフラグが何をし、意図的に何をしないかについては、インスタンス管理者権限を付与するで説明しています。

結果

これで、稼働するインスタンスが手に入りました。あなたのURLで応答するWebアプリ、その隣で動くqueueワーカーとscheduler、名前付きのデータベースボリュームに保存されたデータ、そしてアカウントオーナーとインスタンス管理者を兼ねる自分自身です。クラブのメンバーは自分自身のアカウントを登録できますし、あなたが自分のアカウントに人を招待することもできます。

ひと息つく前にやっておくべきこと

初期状態では、このインスタンスは送信メールを送る代わりにログファイルに書き込むだけです。実際のメーラーを設定するまで、招待、マジックリンク、パスワードリセットは、何も知らせずにどこにも届きません。これは意図的な仕様で、対処は短い作業で済みます。メール配信を設定するを参照してください。

避けるべきよくある間違い

• アプリケーションキーを失うこと。 データベースとは別に、今すぐバックアップを取ってください。キーがなければ、バックアップは暗号文のままです。
• プレースホルダーのデータベースパスワードをそのままにしておくこと。 最初の起動の後ではなく、前に変更してください。
• メール設定を後回しにすること。 最初に来る「招待メールが届かない」という報告は、たいていこれが原因です。

次に読むべきもの

• 飛ばした設定項目をすべてインスタンスを設定するで確認しましょう。
• カタログが大切なものになる前に、バックアップを用意しましょう。
• 新しいバージョンがリリースされたら、インスタンスをアップグレードするに従いましょう。