docs/quick-start.md

クイックスタート: Welley の最小構成デプロイ

1台のLinuxホストでWelleyインスタンスを動かすための、いちばん短い手順です。どのクラウドでも、自前のハードウェアでも使えます。CLIが実際に必要とするフラグだけを使い、ほかはすべて初期値のままにします。

できあがるもの: プラットフォーム、RAGパイプライン、Nginx、Redis、そして同梱のPostgreSQLコンテナです。Let's Encryptの証明書はインストール中に発行されます。マネージドデータベース、CDN、テレメトリー、Slack連携は含まれません。これらについては、AWS EC2とDigitalOceanのガイドをご覧ください。

1. 事前に必要なもの

Linuxホスト

  • Ubuntu 24.04 LTS(または同等の最新のディストリビューション)。
  • 目安として、2 vCPU、4 GB RAM、60 GBのディスク。
  • 固定の公開IPv4アドレス。
  • 受信TCPの 80 と 443 をインターネットに、22 をご自身に対して開けておいてください。80番ポートは、インストール中の証明書の確認と、その後の毎週の更新で必要です。
  • sudo を使える非rootユーザー。このガイドでは、すべてそのユーザーで実行します。以下では <user> と表記します。

DNS

ホストの公開IPを指すレコードを2つ用意します。

レコード 用途
<domain> サイト本体
storage.<domain> アップロードと静的ファイル用(この構成にはCDNがないためです)

始める前に作成してください。CLIは両方の名前がこのホストに解決されるかを確認し、解決されない場合は停止します。

メール用のDNSレコード

--smtp-from アドレスのドメインには、メール認証のレコードが必要です。ないと、Gmail、Outlook、その他の大手プロバイダーは、これまでにメールを受け取ったことのない相手へのメールを破棄することがよくあります。招待も登録確認メールもすべて対象で、迷惑メールフォルダにすら届かず、SMTPプロバイダー側では送信済みと表示されます。

レコード タイプ 値
<mail-domain> TXT SPF。例: v=spf1 include:<provider> ~all(正確な値はSMTPプロバイダーの案内に従ってください)
_dmarc.<mail-domain> TXT DMARC。例: v=DMARC1; p=none; rua=mailto:dmarc@<mail-domain>
<selector>._domainkey.<mail-domain> TXTまたはCNAME DKIM。ドメインを検証するときに、SMTPプロバイダーが生成します

1つのドメインに置けるSPFレコードは1つだけです。すでにある場合は、2つ目を作らず、既存のレコードにプロバイダーを追加してください。SPFまたはDMARCがない場合、create は警告を出しますが、停止はしません。DKIMはセレクター名がプロバイダーごとに異なるため、確認できません。

DKIMは省かないでください。Amazon SESをはじめ、多くのプロバイダーは、初期設定でエンベロープ送信者に自社のドメインを使って送信します。その場合、SPFが確認するのはご自身のドメインではなくプロバイダーのドメインなので、DMARCの判定には加わらず、DMARCを通せるのはDKIMだけです。DKIMの状態は、プロバイダーのコンソールで確認してください。Amazon SESでは、Verified identities で <mail-domain> を開き、DKIM の項目が Successful になっている必要があります。SES Easy DKIMは、<token>._domainkey.<mail-domain> という名前のCNAMEレコードを3つ公開します。

SMTPの認証情報

ホスト、ユーザー、パスワード、送信元アドレスです。プロバイダーはどこでも構いません。プラットフォームがメール確認とパスワードの再設定に使うため、これらがないと、CLIはインストールを行いません。初期設定では、587番ポートでSTARTTLSによるメール送信を行うものとしています。

管理者のメールアドレスも必要です。最初のログインとパスワードの再設定に使います。

2. Dockerをインストールする

お使いのディストリビューションの公式の手順に従ってください: Install Docker Engine。そのあと、ご自身のユーザーがデーモンと通信できるようにします。

sudo usermod -aG docker <user>

いったんログアウトしてからログインし直し、両方が使える状態か確認します。

docker ps
docker compose version

3. CLIをダウンロードする

お使いのホストに合う platform の値を選んでください。

linux/amd64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/amd64" -o wlycli
chmod +x wlycli
./wlycli -v
linux/arm64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/arm64" -o wlycli
chmod +x wlycli
./wlycli -v
darwin/arm64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/arm64" -o wlycli
chmod +x wlycli
./wlycli -v
darwin/amd64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/amd64" -o wlycli
chmod +x wlycli
./wlycli -v

4. デプロイする

./wlycli deploy create \
-d example.com \
-e admin@example.com \
--smtp-host smtp.example.com \
--smtp-user "$MAIL_USER" \
--smtp-password "$MAIL_PASSWORD" \
--smtp-from noreply@example.com

必須のフラグは、この6つがすべてです。このコマンドは、DNSの確認、デプロイ用ファイルの書き出し、Certbotによる証明書の発行、コンテナの起動を行います。数分かかります。

ここで受け入れる初期設定は次のとおりです。

設定 初期値
インストール先ディレクトリ ~/.welley/<project>。<project> は、ドメインの英数字以外の文字をすべて _ に置き換えたものです(example.com は example_com になります)
データベース 同梱のPostgreSQLコンテナ。データはインストール先ディレクトリの下に置かれます
証明書 Certbot経由のLet's Encrypt。週に1回、自動で更新されます
アップロードと静的ファイル https://storage.<domain> から配信されます
アップデート stable チャンネル。毎日確認し、可能な場合はダウンタイムなしで適用されます

5. 最初のログイン

生成された管理者パスワードは、プラットフォームのログに出力されます。

docker logs example_com-platform-blue-1 | grep "Auto-init complete"

https://<domain> を開き、-e で指定した管理者のメールアドレスでサインインして、すぐにパスワードを変更してください。変更するまでは、ログを秘密情報として扱ってください。

6. 結果を確認する

docker ps

nginx、platform-blue、rag-pipeline-blue、postgres、redis、autoheal、snoopy のコンテナが1つずつ表示されるはずです。名前はすべて <project>-<service>-1 の形です。

うまくいかなかったとき

プロジェクトのディレクトリやそのコンテナが残っている間は、create をもう一度実行することはできません。ファイルに問題がなく、一部のコンテナだけが起動に失敗した場合は、何も失わずにコンテナを作り直せます。

./wlycli deploy restart -d example.com

デプロイそのものをやり直す必要がある場合は、いったん削除してから最初からやり直してください。この操作では、同梱のデータベースもほかのものと一緒に削除されます。

./wlycli deploy delete -d example.com --yes-please-delete-all-the-data

ほかの文書