【Windows】GitHub上のLaravel Sailプロジェクトをローカルにcloneして環境を構築する

はじめてLaravel Sailのプロジェクトに参加する際に環境構築で躓きました。
Laravelのプロジェクトは過去にもアサインしたことがあったのですが、Laraval Sailとは…？？？という状態でした。

WindowsはWSL2を経由する必要があるんですね～。ここが最初分からなくて環境整えるだけで丸一日かかりました。

WSL2はWindows上でLinuxを実行できる機能のことです。

プロジェクト自体はバックエンドの方が作成してGitHubに上げてくれていたのですが、git cloneしてからのローカルで環境を整えるのにも苦労しました…。既に忘れかけているので、記憶をたどりながら書き留めておきます。

前提・環境

Docker Desktopが既にインストールしてある前提です。

Laravel Sailでの新規プロジェクト立ち上げではなく、Laravel Sail（WSL2）を使用するのが初めてで、GitHubのLaravel Sailプロジェクトをcloneして開発に参加することを想定しています。

ざっくりとした手順

ざっくりとした手順はこのようになります。

WSL2・Ubuntuのインストール

Powershellを管理者モードで立ち上げて、WSLの状態を確認します。

wsl -l -vのコマンドでWSLの状態の確認ができるので、下記の状態になっていればOKです。

>  wsl -l -v
  NAME                   STATE           VERSION
* Ubuntu                 Running         2
  docker-desktop-data    Running         2
  docker-desktop         Running         2

この設定ができていたらこの章は飛ばして大丈夫なので、次の手順GitHubからプロジェクトをクローンして開発者モードで起動するへ。

docker-desktopとdocker-desktop-dataが表示されない場合はDocker Desktopがインストールされていないので、そちらを先にインストールしてください。

下記のように、Ubuntuが表示されない場合はUbuntuが未インストールの場合へ。

>  wsl -l -v
  NAME                   STATE           VERSION
* docker-desktop         Running         2
  docker-desktop-data    Running         2

下記のようなメッセージが出てきた場合、wslが未インストールなのでWSLが未インストールの場合へ。

> wsl -l -v
このアプリケーションには、Linux 用 Windows サブシステムオプション コンポーネントが必要です。
次を実行してインストールする: wsl.exe --install --no-distribution
変更を有効にするには、システムの再起動が必要な場合があります。
エラー コード: Wsl/WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED

>  wsl -l -v

Copyright (c) Microsoft Corporation. All rights reserved.

使用方法: wsl.exe [Argument]

引数:

    --install <Options>
        Linux 用 Windows サブシステムの機能をインストールします。オプションが指定されていない場合は、
        既定のディストリビューションと共に、推奨される機能がインストールされます。

        既定のディストリビューションおよびその他の有効なディストリビューションの一覧を表示するには、
        'wsl --list --online' を使用してください。

(...省略)

Ubuntuが未インストールの場合

wsl --install -d UbuntuのコマンドでUbuntuをインストールします。

> wsl --install -d Ubuntu
ダウンロード中: Ubuntu
インストール中: Ubuntu
Ubuntu はインストールされました。
Ubuntu を起動しています...
Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username:

WSLが未インストールの場合

Windows の機能の有効化または無効化を開きます。

• Linux用Windowsサブシステム
• 仮想マシンプラットフォーム

このふたつにチェックが付いていることを確認します。
チェックが無い場合はチェックを付けてOKを押します。その後PCを再起動します。

PCを再起動したら、もう一度Powershellを管理者モードで立ち上げます。

wsl --installでwslをインストールします。

> wsl --install
インストール中: 仮想マシン プラットフォーム
仮想マシン プラットフォーム はインストールされました。
インストール中: Linux 用 Windows サブシステム
Linux 用 Windows サブシステム  はインストールされました。
インストール中: Linux 用 Windows サブシステム
Linux 用 Windows サブシステム  はインストールされました。
インストール中: Ubuntu
Ubuntu はインストールされました。
要求された操作は正常に終了しました。変更を有効にするには、システムを再起動する必要があります。

要求された操作は正常に終了しました。変更を有効にするには、システムを再起動する必要があります。
と表示されればWSLのインストール完了です。Ubuntuも一緒にインストールされます。

インストールが完了したら、PCを再起動します。

Ubuntuの初期設定

ユーザー名とパスワードを入力するよう求められるので、指示通り入力します。

Enter new UNIX username: ここにユーザー名

任意のユーザー名を入力してエンターを押します。

New password: ここにパスワード（見えない）

パスワードを入力してエンターを押します。
入力したパスワードは表示されないので、入力しても何も入力してないように見えるので注意です。

Retype new password: もう一回同じパスワード（見えない）

確認でもう一度先程のパスワードを入力してエンターを押します。

Installation successful!が表示されればWSL2とUbuntuの準備完了です。

WSLのバージョンと既定のディストリビューションの設定

もう一度新しくPowerShellを開いて、WSLの状態を確認します。

> wsl -l -v
  NAME                   STATE           VERSION
* docker-desktop-data    Running         2
  docker-desktop         Running         2
  Ubuntu                 Running         2

Ubuntuがインストールされていますね。

既定のディストリビューションに*が付きますが、これだとdocker-desktop-dataが既定になっているので、wsl --setdefault Ubuntuコマンドで既定をUbuntuに変更します。

> wsl --setdefault Ubuntu
この操作を正しく終了しました。

もしもVERSIONが1になっていたら、wsl --set-version <NAME> <VERSION>のコマンドでバージョンを2に変更します。

> wsl --set-version Ubuntu 2
WSL 2 との主な違いについては、https://aka.ms/wsl2
 を参照してください
変換中です。これには数分かかる場合があります。
この操作を正しく終了しました。

もう一度wsl -l -vで確認して、下記のようになっていたら設定完了です。

>  wsl -l -v
  NAME                   STATE           VERSION
* Ubuntu                 Running         2
  docker-desktop-data    Running         2
  docker-desktop         Running         2

GitHubからプロジェクトをクローンして開発者モードで起動する

エクスプローラーのアドレスバーに\\wsl$を入力すると、wslのディレクトリが表示されます。

\\wsl$\Ubuntu\home\ユーザー名のフォルダ内にプロジェクトをcloneします。（git cloneの方法は特別変わらないので省きます。）

\\wsl$\Ubuntu\home\ユーザー名には設定ファイルもあってごちゃごちゃしてるので、プロジェクトを置く場所として\\wsl$\Ubuntu\home\ユーザー名\projectなど任意のディレクトリを作成してもOKです。

.envファイルの作成

.env.example などのファイルがあると思うので、それを元にして .env を作ります。

丸コピーで行ける場合もあれば、パスワードやトークンが含まれていたらそこは書いてないはず。
ここはプロジェクトによるので、分からなければプロジェクト作成者に聞きましょう。

Dockerを起動

PowerShellやコマンドプロントで、プロジェクトのディレクトリに移動して、docker-compose up -dでDockerを起動します。（私はVS Codeのターミナルを使用しています。）

> docker-compose up -d

ここでエラーが出る場合はポート番号の設定などを確認してください。

sailのエイリアスを設定

sailのコマンドが./vendor/bin/sailなのですが、長くて使いにくいのでsailで起動できるように設定します。

\\wsl$\Ubuntu\home\ユーザー名のフォルダ内に.bashrcというファイルがあるので、最下部に下記コードを追加して保存します。

alias sail='[ -f sail ] && sh sail || sh vendor/bin/sail'

composerの設定

Ubuntuを開きます。Linux用のターミナルのようなものです。

\\wsl$\Ubuntu\home\ユーザー名フォルダがルートになっていて、最初はルートにいるので、cdコマンドで　作成したプロジェクトディレクトリに移動し、sailを起動します。

$ sail up -d

ちょっと時間がかかるので待ちます。

表示が止まって、エラーが出ていなければ大丈夫です。

sailが起動出来たら、composerをインストールします。

$ sail composer install

次のコマンドを実行します。

$ sail php artisan key:generate && sail php artisan migrate && sail npm install

このコマンドでやっていることは下記になります。

• アプリケーションキー (APP_KEY) を生成して、.envファイルに追加する
• データベースに定義されたテーブルやカラムを反映
• package.jsonのパッケージのインストール（node_modulesフォルダができる）

ここまでで初期設定は完了です。

後はsail npm run devで開発モードでのビルドが起動します。

$ sail npm run dev

> dev
> vite


  VITE v5.3.1  ready in 395 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://xxx.xx.x.x:xxxx/
  ➜  press h + enter to show help

  LARAVEL v11.10.0  plugin v1.0.4

  ➜  APP_URL: http://localhost

こんな感じで表示されますので、APP_URLにブラウザでアクセスして確認します。
私は別途ポート番号を変更していたので、上記の表示でもhttp://localhost:88/が実際のURLになっていました。

環境によってURL変わってくるので、http://localhostで表示されなければポート番号を確認してください。

これでやっと作業開始です…！長かった…

ターミナルについて

注意点ですが、ターミナルの使い分けが必要になります。

Linux側で動作しているsail関連はUbuntuから。

それ以外のWindows側、git関連などはいつものターミナル（コマンドプロンプトやPowerShell、VS Codeのターミナルなど）から操作します。

切り替えがややこしい方はWindows Terminalを使うと便利なようです。私は慣れるまでどっちを使ってるか意識しておきたかったのであえてそのままいきました。