クイックスタート - basecamp/fizzy

環境構築とセットアップ

Fizzyの開発環境は、bin/setupスクリプトを実行することで自動的に構築される。このスクリプトは、必要なツールのインストール、RubyGemsの依存関係解決、データベースの準備を一括して実行する（docs/development.md:1-80）。

前提条件

セットアップスクリプトは以下のツールを自動的にインストールしようとする：

ツール	用途	インストール方法
gum	ターミナルUIのスタイリング	Homebrew/pacman
mise	Rubyバージョン管理	Homebrew/pacman
gh	GitHub CLI	Homebrew/pacman

これらのツールがシステムに存在しない場合、スクリプトは自動的にインストールを試みる（bin/setup:1-158）。Homebrew（macOS）またはpacman（Arch Linux）が前提となる。その他のディストリビューションの場合、手動でのインストールが必要。

セットアップの実行

基本的なセットアップは以下のコマンドで実行できる：

bash
1bin/setup

データベースをリセットして初期データを再投入する場合：

bash
1bin/setup --reset

セットアップスクリプトの内部処理は以下の順序で実行される（bin/setup:1-158）：

Rubyのインストール（mise経由）
システムパッケージのインストール（imagemagick、vips、ffmpeg等）
RubyGemsのインストール（bundle install）
データベースの準備（rails db:prepareまたはrails db:reset）
シードデータの投入（必要に応じて）
ログ・一時ファイルのクリーンアップ

システムパッケージについて

macOS（Homebrew）環境では、以下のパッケージがインストールされる：

imagemagick
openslide
vips
gitleaks

Arch Linux（pacman）環境では、より多くのパッケージが含まれる：

imagemagick, mariadb-libs, openslide, libvips, libheif, libwebp, libjxl, libraw, poppler-glib, libcgif, ffmpeg, rav1e, svt-av1, gitleaks

これらは画像処理、動画エンコーディング、データベース接続等の機能に必要なライブラリ群である（bin/setup:1-158）。

開発サーバーの起動

セットアップ完了後、以下のコマンドで開発サーバーを起動できる（docs/development.md:1-80）：

bash
1bin/dev

アクセス方法

開発環境では、以下のURLでアプリケーションにアクセス可能：

http://fizzy.localhost:3006

このアドレスは、ローカル開発環境向けに設定されたホスト名とポート番号である（docs/development.md:1-80）。

ログイン認証

開発環境へのログインは、以下の認証情報を使用：

メールアドレス: david@example.com
認証コード: ブラウザコンソールから取得

認証コードは、ブラウザの開発者ツールのコンソールに出力されるため、そこから確認して入力する（docs/development.md:1-80）。

メールプレビュー機能

送信されるメールのプレビューは以下のURLで確認可能：

http://fizzy.localhost:3006/rails/mailers

また、letter_opener gemを使用して、送信されたメールを自動的にブラウザで開く機能が提供されている。この機能の有効/無効は以下のコマンドで切り替えられる（docs/development.md:1-80）：

bash
1bin/rails dev:email

このコマンドは、内部的にtmp/email-dev.txtファイルを作成または削除することで機能を制御している。

データベース設定

FizzyはデフォルトでSQLiteを使用し、MySQLもサポートしている。データベースアダプターの切り替えは環境変数DATABASE_ADAPTERで制御可能（docs/development.md:1-80）。

SQLiteを使用する場合（デフォルト）

特別な設定なしで、デフォルトのSQLiteが使用される。

MySQLを使用する場合

MySQLで開発する場合、以下のように環境変数を設定してセットアップを実行する（docs/development.md:1-80）：

bash
1DATABASE_ADAPTER=mysql bin/setup --reset
2DATABASE_ADAPTER=mysql bin/ci

MySQL環境のセットアップでは、DockerコンテナとしてMySQL 8.4が自動的に起動される。セットアップスクリプトは以下の処理を実行する（bin/setup:1-158）：

localhost:3306でのMySQL稼働確認
既存コンテナ（fizzy-mysql）の再利用または新規作成
コンテナ起動待機

設定ファイルの構造

データベース設定はconfig/database.ymlで管理されている。このファイルは、SaaSモードとOSSモードで異なる設定ファイルを読み込む動的な構造を持つ（config/database.yml:1-9）：

SaaSモード: saas/config/database.yml
OSSモード: config/database.{adapter}.yml（adapterはsqliteまたはmysql）

CI環境でのテスト

リモートCIパイプラインでは、SQLiteとMySQLの両方に対してテストが実行される（docs/development.md:1-80）。

テストの実行

Fizzyでは、フィードバックループの短縮のため、単体テストと完全なCIテストの2種類のテスト実行方法が提供されている（docs/development.md:1-80）。

単体テスト

高速なフィードバックが必要な場合、以下のコマンドを使用：

bash
1bin/rails test

CIテスト

完全な継続的インテグレーションテストは以下のコマンドで実行：

bash
1bin/ci

テスト用依存関係

テスト環境では、以下のgemが使用されている（Gemfile:1-66）：

gem	用途
capybara	ブラウザテスト
selenium-webdriver	ブラウザ自動化
webmock	HTTPリクエストのモック
vcr	HTTP通信の記録・再生
mocha	モッキングライブラリ

Web Push通知の設定

Fizzyは、ブラウザプッシュ通知の送信にVAPID（Voluntary Application Server Identification）キーを使用している。開発環境で通知機能を有効にするには、キーペアの生成と環境変数の設定が必要（docs/development.md:1-80）。

VAPIDキーの生成

web-push gemを使用して、以下のRubyコードでキーペアを生成できる（docs/development.md:1-80）：

ruby
1vapid_key = WebPush.generate_key
2
3puts "VAPID_PRIVATE_KEY=#{vapid_key.private_key}"
4puts "VAPID_PUBLIC_KEY=#{vapid_key.public_key}"

環境変数の設定

生成されたキーは、以下の環境変数に設定する必要がある：

VAPID_PRIVATE_KEY
VAPID_PUBLIC_KEY

web-push gemは、Gemfileで依存関係として定義されている（Gemfile:1-66）。

セットアップフロー

以下のフローチャートは、bin/setupスクリプトの実行フローを示している：

正在加载图表渲染器...

常見問題與排錯

1. ツールインストールエラー

問題: gum、mise、ghのインストールに失敗する。

原因: Homebrewまたはpacmanがシステムにインストールされていない。

解決策: 以下のいずれかの方法でツールを手動インストールする：

bash
1# macOS (Homebrew)
2brew install gum mise gh
3
4# Arch Linux (pacman)
5sudo pacman -S gum mise github-cli
6
7# その他の環境
8# gum: https://github.com/charmbracelet/gum
9# mise: https://mise.jdx.dev/installing-mise.html
10# gh: https://github.com/cli/cli#installation

2. MySQL接続エラー

問題: DATABASE_ADAPTER=mysql設定時に接続エラーが発生する。

原因: MySQLコンテナが起動していない、またはポート3306が使用中。

解決策: 以下のコマンドでコンテナの状態を確認・再起動する：

bash
1# コンテナの状態確認
2docker ps -a -f name=fizzy-mysql
3
4# 既存コンテナの再起動
5docker start fizzy-mysql
6
7# コンテナの再作成（必要に応じて）
8docker rm -f fizzy-mysql
9DATABASE_ADAPTER=mysql bin/setup --reset

セットアップスクリプトは、MySQL 8.4イメージを使用してコンテナを自動作成する（bin/setup:1-158）。

3. Rubyバージョン不一致

問題: インストールされるRubyバージョンが期待と異なる。

原因: .ruby-versionファイルとmiseの設定が同期していない。

解決策: miseは.ruby-versionファイルを参照してRubyをインストールする。以下のコマンドで確認・再インストール可能：

bash
1# 現在のRubyバージョン確認
2mise current ruby
3
4# Rubyの再インストール
5mise install ruby --force

Dockerfileでは、Ruby 3.4.7がベースイメージとして指定されている（Dockerfile:1-83）。

4. ポート3006が使用中

問題: 開発サーバー起動時にポート3006が使用中というエラーが発生する。

原因: 他のプロセスがポート3006を使用している。

解決策: 以下のコマンドで使用中のプロセスを確認・停止する：

bash
1# ポート使用状況の確認
2lsof -i :3006
3
4# プロセスの停止（PIDを指定）
5kill -9 <PID>

5. ブラウザコンソールに認証コードが表示されない

問題: ログイン時に認証コードがブラウザコンソールに表示されない。

原因: JavaScriptエラーまたはコンソールのフィルタ設定。

解決策: ブラウザの開発者ツールで以下を確認する：

コンソールのフィルタが「すべてのレベル」を表示する設定になっているか
JavaScriptエラーが発生していないか
ページをリロードして再試行

次のステップ

クイックスタートが完了したら、以下のトピックについて詳細を確認することを推奨する：

アーキテクチャ概要: アプリケーションの全体構造と主要コンポーネントの理解
設定ガイド: 環境変数、データベース、ストレージの詳細設定
デプロイメント: 本番環境へのデプロイ手順（Kamal、Docker等）
機能拡張: カスタム機能の追加方法

SaaS版の設定については、saas/ディレクトリ内のファイルが参考になる。ただし、SaaS gemはプライベートリポジトリに依存しており、第三者による使用は想定されていない（docs/development.md:1-80）。