【WSL入門】Ubuntu on WSL2 に開発ツールを一式そろえる — Git / nvm / pnpm / AWS CLI / Terraform

前回の記事では、Windows に WSL2 を導入して Ubuntu が動くところまでを扱いました。
ただ、素の Ubuntu はあくまで「まっさらな Linux」です。ここから実際に開発を始めるには、バージョン管理・ランタイム・クラウド操作のツールを自分で入れていく必要があります。

この記事では、すべて公式ドキュメントに載っている手順だけを使って、次のツールを順番にセットアップします。

基本ツール（ビルド環境・ネットワークツール）
Git（＋ Windows 側と認証情報を共有する Git Credential Manager）
nvm → Node.js
pnpm
AWS CLI v2
Terraform

各セクションの末尾に出典 URL を置いてあるので、手順が古くなったと感じたらそこを見に行ってください。記事末尾には出典一覧もまとめています。

検証環境
Windows 11 / WSL2 / Ubuntu 24.04 LTS（x86_64）
確認日：2026年7月28日

バージョン番号は執筆時点のものです。インストールコマンド自体は基本的に「常に最新を取ってくる」形になっているので、そのまま実行して問題ありません。

はじめに：WSL開発の大原則

コマンドに入る前に、ひとつだけ。Microsoft の公式ドキュメントが繰り返し書いている重要な原則があります。

使う予定のツールと同じ OS 側にファイルを置く。
Linux ツールで Linux コマンドラインから作業しているなら、最速のパフォーマンスを出すためにファイルは WSL ファイルシステムに格納します。

具体的には、プロジェクトは次の場所に置きます。

✅ \\wsl$\Ubuntu\home\<ユーザー名>\Project（Linux 側 = ~/Project）
❌ C:\Users\<ユーザー名>\Project（= WSL から見た /mnt/c/Users/...）

/mnt/c/ 配下はファイルシステムをまたぐため、npm install や git status が体感でわかるほど遅くなります。第2弾でこれから入れるツールも、すべて Linux 側のホームディレクトリを前提に使ってください。

出典：WSL 開発環境を設定する — Microsoft Learn

1. まずは基本ツール

Ubuntu を起動したら、最初にやることはパッケージの更新です。Microsoft の公式ドキュメントにもこう書かれています。

ディストリビューションの優先パッケージマネージャーを使用して、パッケージを定期的に更新およびアップグレードすることをお勧めします。
Windows では、Linux ディストリビューションの更新やアップグレードは自動的に行われません。

sudo apt update && sudo apt upgrade

apt update はパッケージ一覧の更新、apt upgrade は実際のアップグレードです。WSL は勝手にアップデートしてくれないので、これは月イチくらいで習慣にしておくのがおすすめです。

続いて、この記事の後半で必要になるツールをまとめて入れておきます。

sudo apt install -y \
  build-essential \
  curl \
  wget \
  unzip \
  ca-certificates \
  gnupg \
  software-properties-common

それぞれの役割は以下の通りです。

build-essential — gcc / make など。Node.js のネイティブモジュールをビルドするときに必要になります
curl / wget — インストールスクリプトの取得に使用。この後ほぼ全セクションで登場します
unzip — AWS CLI の zip 展開に必須（AWS 公式が要件として明記）
ca-certificates / gnupg — HTTPS 通信と GPG 署名検証に使用。Terraform のリポジトリ登録で必要
software-properties-common — add-apt-repository コマンドを提供。Git の PPA 追加で使用

HashiCorp の公式チュートリアルも、Terraform を入れる前段としてこう書いています。

sudo apt-get update && sudo apt-get install -y gnupg software-properties-common

出典：

WSL 開発環境を設定する — Microsoft Learn

Install Terraform — HashiCorp Developer

2. Git

2-1. Git は「Windows と WSL の両方」に入れる

まず理解しておきたい前提。Microsoft の公式ドキュメントはこう書いています。

Git を使用する予定の各ファイルシステムに Git をインストールする必要があります。

WSL は Windows とは別のファイルシステムを持っています。つまり Windows 側の Git と WSL 側の Git は完全に別物で、バージョンも設定ファイルも別々です。この記事では WSL 側を入れますが、Windows 側にも Git for Windows を入れておくことが推奨されています（理由は後述の Credential Manager のところで説明します）。

2-2. インストール

Ubuntu にはたいてい Git が最初から入っていますが、バージョンが古いことが多いです。Git 公式サイトは、Ubuntu/Debian で最新の安定版を入れる方法として PPA を案内しています。

sudo add-apt-repository ppa:git-core/ppa
sudo apt update
sudo apt install git

ppa:git-core/ppa は Git のメンテナが管理している公式の PPA で、Ubuntu 標準リポジトリより新しいバージョンが提供されます。

バージョンにこだわらないなら、標準リポジトリからでも構いません。

sudo apt install git

確認：

git --version

2-3. ユーザー情報の設定

コミットに刻まれる名前とメールアドレスを設定します。

git config --global user.name "Your Name"
git config --global user.email "youremail@domain.com"

設定ファイルを直接編集したいときは nano ~/.gitconfig で開けます。

2-4. Git Credential Manager で Windows と認証情報を共有する

ここが WSL ならではの便利ポイントです。

Git Credential Manager（GCM） は .NET 製の資格情報ヘルパーで、GitHub・Azure DevOps・Bitbucket の多要素認証に対応しています。認証トークンを Windows 資格情報マネージャーに安全に保存してくれるので、一度認証すれば以降は再認証なしで push / pull できます。

WSL で使うには Windows 10 バージョン 1903 以降が必要です（GCM が WSL 側の Git と連携するために wsl.exe を使うため）。

推奨されるのは、Windows 側に Git for Windows を入れる方法です。GCM は Git for Windows に同梱されているため、インストール時に「GCM を既定の資格情報ヘルパーにする」を選ぶだけで済みます。

Git for Windows を入れたら、WSL 側で GCM が見えているか確認します。

git-credential-manager.exe --version

2.7.3+5fa7116896c82164996a609accd1c5ad90fe730a

このようにバージョンが返ってくればOKです。

⚠️ ここは Microsoft 公式ドキュメントの記述にひとつ罠があります。
公式には確認コマンドとして git --version; git credential-manager --version と書かれていますが、WSL 側でこれを実行すると失敗します。
$ git --version; git credential-manager --version
git version 2.54.0
git: 'credential-manager' is not a git command. See 'git --help'.
git credential-manager という書き方は、Git が「git-credential-manager という名前の実行ファイル」を PATH から探す仕組みです。しかし WSL から見える実体は git-credential-manager.exe で、Linux 版の Git は拡張子 .exe を補完しません。そのため見つけられずにエラーになります。

GCM が入っていないわけではないので、慌てなくて大丈夫です。上記のように .exe を明示して実行すれば確認できます。ファイルの存在を直接見てもOKです。
ls -l "/mnt/c/Program Files/Git/mingw64/bin/git-credential-manager.exe"

続いて、WSL 側の Git に「認証は GCM に任せる」と設定します（GCM 公式リポジトリの手順）。

git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

パス中の空白を \ でエスケープしている点に注意してください。設定されたか確認するには次のコマンドを実行します。

git config --global credential.helper

これで、WSL 内で実行する git 操作はすべて GCM 経由になります。Windows 側でキャッシュ済みの資格情報があればそれが使われ、まだなければ、Linux コンソールで作業していても Windows のダイアログが出てきて認証を求められます。

Azure DevOps / Azure Repos を使う場合は、追加でこの設定が必要です。

git config --global credential.https://dev.azure.com.useHttpPath true

注意点が2つあります。

GCM は WSL 側の git config を見ません。 GCM は Windows アプリとして動くため、設定の参照先は Windows 側の %UserProfile%\.gitconfig です。プロキシ設定などは Windows 側と WSL 側（\\wsl$\distro\home\$USER\.gitconfig）の両方に書く必要があります。
GCM は HTTP(S) リモートでのみ動作します。 SSH で運用したい場合は GCM ではなく、GitHub の SSH 接続ガイドに従って鍵を設定してください。

なお、Git for Windows を入れずに WSL 側だけで完結させることも可能ですが、その場合 GCM は Linux アプリとして動くため、Windows の認証・資格情報ストレージ機能は使えません。手順はGCM 公式ドキュメントの該当セクションにあります。

2-5. 改行コード（ここでハマる人が多い）

Windows と Linux で同じリポジトリを触ると、Git が「大量のファイルが変更された」と報告してくることがあります。中身は同じで、改行コードだけが違うという状態です。

対策は次のどちらかです。

リポジトリに .gitattributes を置いて改行コードを明示する（推奨）
Windows 側でグローバルに改行変換を無効化する

詳しい対処は VS Code のトラブルシューティングドキュメントにまとまっています。

2-6. .gitignore

プロジェクトには .gitignore を置きましょう。GitHub が用途別のテンプレート集を公開しているので、そこからコピーするのが早いです。

出典：

WSL での Git の使用を開始する — Microsoft Learn

Git — Downloading Package (Linux)

Git Credential Manager — WSL ドキュメント

3. nvm と Node.js

3-1. なぜ nvm なのか

Node.js は apt install nodejs でも入りますが、Ubuntu の標準リポジトリのバージョンはかなり古く、しかもプロジェクトごとにバージョンを切り替えられません。nvm（Node Version Manager） を使えば、複数バージョンの Node.js を共存させてコマンド一発で切り替えられます。

3-2. インストール

nvm 公式リポジトリが案内しているインストールコマンドです（執筆時点の最新は v0.40.6）。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

wget 派の人はこちら。

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

⚠️ URL にバージョン番号（v0.40.6）が直接埋め込まれている点に注意してください。この記事を読んでいる時点でより新しいバージョンが出ている可能性があります。実行前に nvm-sh/nvm の Releases で最新タグを確認して、URL のバージョン部分を置き換えるのが確実です。

スクリプトは ~/.bashrc に以下を自動で追記します（うまく入らなかった場合は手動で追記してください）。

export NVM_DIR="$( [ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

追記後、ターミナルを一度閉じて開き直します（または source ~/.bashrc）。

3-3. 確認

command -v nvm

nvm と表示されれば成功です。

⚠️ which nvm では確認できません。 nvm は実行ファイルではなくシェル関数として読み込まれるためです。ここは公式 README がわざわざ注意書きしているポイントで、「インストールしたのに which で出てこない」と焦る人が多い箇所です。

3-4. Node.js を入れる

nvm install --lts     # 最新のLTSを入れる（本番用途はこれ）
nvm install 24        # メジャーバージョンを指定して入れる
nvm use 24            # 使うバージョンを切り替える
node -v               # 確認

2026年7月現在の Node.js のリリース状況はこうなっています。

Active LTS：v24（Krypton） ← 本番環境で推奨されるのはこれ
Maintenance LTS：v22（Jod）
Current：v26

迷ったら nvm install --lts で Active LTS を入れておけば間違いありません。

💡 プロジェクトのルートに .nvmrc というファイルを作ってバージョン（例：24）を書いておくと、そのディレクトリで nvm use するだけで切り替わります。チーム開発では地味に効きます。

出典：

nvm-sh/nvm — GitHub

Node.js Releases

4. pnpm

pnpm は npm 互換のパッケージマネージャで、ディスク上で依存パッケージを共有する仕組みにより、インストールが速くディスク消費も小さいのが特徴です。

pnpm 公式ドキュメントは3つの方法を案内しています。順に見ていきます。

方法A：Corepack 経由（公式が推奨）

corepack enable pnpm
corepack use pnpm@latest-11

Corepack を使う利点は、package.json にパッケージマネージャのバージョンが記録され、チーム全員が同じバージョンを使えることです。再現性を重視するプロジェクトに向いています。

⚠️ Node.js 25 以降は Corepack が同梱されません。
2025年3月19日、Node.js の TSC は v25 以降で Corepack を配布しないことを正式に決定しました。Node.js 24 以前では experimental 機能として引き続き利用できます。

Node 25 以降で Corepack を使いたい場合は、別途インストールが必要です。
npm install -g corepack
Active LTS の v24 を使っている限りは同梱されているので、当面はそのまま corepack enable pnpm で動きます。

方法B：npm 経由

Node.js が入っていれば一番シンプルです。

npm install -g pnpm@latest-11

Corepack の同梱状況に左右されないので、この記事の構成（nvm で Node を入れる）なら方法Bが一番素直だと思います。

方法C：スタンドアロンスクリプト

Node.js なしでも入れられる方法です。

curl -fsSL https://get.pnpm.io/install.sh | sh -

wget 派：

wget -qO- https://get.pnpm.io/install.sh | sh -

バージョンを指定したい場合：

curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=<version> sh -

注意事項と確認

公式ドキュメントに記載されている注意点です。

Node.js の最小要件は v22（pnpm 11.x の場合）。nvm で v24 LTS を入れていれば問題ありません
最小構成の Linux コンテナでは libatomic.so.1 が別途必要になる場合があります
Intel Mac ではスタンドアロン版が動作しないため npm / Corepack / Homebrew を使う、という記述もあります（WSL では無関係ですが念のため）

確認：

pnpm --version

執筆時点の最新は 11.17.0 です。

出典：

pnpm Installation — 公式ドキュメント

Node.js TSC Votes to Stop Distributing Corepack

pnpm/pnpm Releases — GitHub

5. AWS CLI v2

5-1. インストール（クイック版）

AWS 公式ドキュメントが「コピペ用」として提示している3行です。x86_64（Intel/AMD の 64bit）向け。

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

ARM 環境（Snapdragon 搭載 PC など）の場合は URL を差し替えます。

curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

デフォルトでは /usr/local/aws-cli にファイルが置かれ、/usr/local/bin にシンボリックリンクが張られます。sudo はこれらのディレクトリへの書き込み権限のために必要です。

確認：

aws --version

aws-cli/2.36.9 Python/3.13.4 Linux/5.15.167.4-microsoft-standard-WSL2 exe/x86_64.ubuntu.24

こんな出力が返ればOKです（バージョンや環境の部分は各自で異なります）。

aws コマンドが見つからない場合は、ターミナルを再起動してみてください。

5-2. 【推奨】署名を検証してからインストールする

AWS 公式は「上記のクイック手順はダウンロードの整合性を検証していません」と明記しています。zip は PGP 署名されているので、検証したほうが安全です。

手順1：GPG をインストール（基本ツールのセクションで入れていれば不要）

sudo apt install gnupg

手順2：AWS CLI の公開鍵をファイルに保存

aws-cli-key.asc などのファイル名で、以下を保存します。

鍵の詳細は以下の通りです。ここが一致していることを確認してください。

Key ID:           A6310ACC4672475C
Type:             RSA
Size:             4096/4096
Created:          2019-09-18
Expires:          2027-07-01
User ID:          AWS CLI Team <aws-cli@amazon.com>
Key fingerprint:  FB5D B77F D5C1 18B8 0511  ADA8 A631 0ACC 4672 475C

手順3：鍵をインポート

gpg --import aws-cli-key.asc

手順4：署名ファイルをダウンロード

curl -o awscliv2.sig https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip.sig

手順5：検証

gpg --verify awscliv2.sig awscliv2.zip

Good signature from "AWS CLI Team <aws-cli@amazon.com>" が出れば成功です。

このとき WARNING: This key is not certified with a trusted signature! という警告が出ますが、これは想定内で問題ありません。自分の PGP 鍵と AWS の鍵の間に信頼の連鎖がないだけです。AWS 公式ドキュメントにもそう明記されています。

検証が通ったら、展開してインストールします。

unzip awscliv2.zip
sudo ./aws/install

5-3. アップデート方法

AWS CLI v2 は自動更新されません。更新するときは新しいインストーラをダウンロードし直して --update を付けて実行します。

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip -u awscliv2.zip
sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update

unzip -u（update フラグ）を使うと、上書き確認のプロンプトをスキップできます。

既存のインストール先がわからなくなったら、次のコマンドで調べられます。

which aws                    # --bin-dir に渡すパス
ls -l /usr/local/bin/aws     # リンク先 = --install-dir に渡すパス

5-4. 補足：snap という選択肢

常に最新版でよく、バージョン固定が不要なら snap も公式サポートされています。

sudo snap install aws-cli --classic

snap は自動更新されるのがメリットですが、マイナーバージョンを選ぶ組み込みサポートがないため、チームでバージョンを固定したい場合はコマンドラインインストーラのほうが適している、と公式は説明しています。

なお、AWS 公式ドキュメントは「AWS は snap 以外のサードパーティリポジトリを管理していないため、最新版が含まれる保証がない」と注意しています。apt install awscli は避けたほうが無難です。

出典：Installing or updating to the latest version of the AWS CLI — AWS ドキュメント

6. Terraform

Terraform は HashiCorp が公式の apt リポジトリを提供しているので、一度登録してしまえば以降は apt upgrade で更新できます。

6-1. GPG キーを登録

wget -O- https://apt.releases.hashicorp.com/gpg | \
  gpg --dearmor | \
  sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg > /dev/null

6-2. キーの fingerprint を検証

公式チュートリアルはこのステップを挟んでいます。

gpg --no-default-keyring \
  --keyring /usr/share/keyrings/hashicorp-archive-keyring.gpg \
  --fingerprint

出力された fingerprint が、HashiCorp が公式に公開している署名鍵のものと一致するか確認してください。

6-3. リポジトリを追加

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | \
  sudo tee /etc/apt/sources.list.d/hashicorp.list

長いですが、やっていることは単純です。

$(dpkg --print-architecture) — CPU アーキテクチャを自動判定
signed-by=... — さっき登録したキーでのみ署名検証する指定
$(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) — Ubuntu のコードネーム（noble など）を自動取得。取れなければ lsb_release -cs にフォールバック

6-4. インストール

sudo apt update
sudo apt-get install terraform

確認：

terraform -version

執筆時点の最新安定版は v1.15.8（2026年7月8日リリース）です。

6-5. タブ補完を有効にする

これは入れておくと体験がかなり変わります。

terraform -install-autocomplete

実行後、シェルを再起動すると terraform pl → Tab で terraform plan が補完されるようになります。

出典：

Install Terraform — HashiCorp Developer

Install Terraform（チュートリアル） — HashiCorp Developer

7. 動作確認

最後にまとめて確認しましょう。

git --version
node -v
npm -v
pnpm --version
aws --version
terraform -version

執筆時点（2026年7月28日）の各バージョンは以下の通りです。参考までに。

ツール	執筆時点のバージョン	インストール方法
Git	2.5x 系（PPA の最新安定版）	`ppa:git-core/ppa`
nvm	v0.40.6	install.sh
Node.js	v24（Active LTS）	`nvm install --lts`
pnpm	11.17.0	npm または Corepack
AWS CLI	2.36.9	公式インストーラ（zip）
Terraform	1.15.8	HashiCorp apt リポジトリ

ハマりどころまとめ

第2弾を通して出てきた注意点を、最後にもう一度並べておきます。

1. /mnt/c/ にプロジェクトを置かない
ファイルシステムをまたぐと明確に遅くなります。プロジェクトは ~/ 配下へ。

2. Windows 側と WSL 側は別環境
Git は両方に必要。git config も別々に保存されます。「Windows で設定したのに WSL で効かない」は仕様です。

3. which nvm は使えない
nvm はシェル関数なので command -v nvm で確認します。

4. Node.js 25 以降は Corepack が同梱されない
pnpm を Corepack で管理している場合、Node をアップグレードしたタイミングで壊れます。CI や Dockerfile も要チェックです。

5. AWS CLI は自動更新されない
--update を付けて再インストールする必要があります。忘れがちなのでカレンダーに入れておくのがおすすめです。

6. Git の改行コード
Windows と Linux をまたぐと大量の差分が出ます。.gitattributes で明示するのが確実です。

7. git credential-manager --version は WSL では動かない
Microsoft 公式ドキュメントに載っている確認コマンドですが、Linux 版 Git は .exe を補完しないため is not a git command になります。git-credential-manager.exe --version と書けば動きます。GCM が入っていないわけではありません。

おわりに

これで、WSL2 上の Ubuntu に開発の基礎セットがそろいました。Git でコードを管理し、Node.js/pnpm でフロントエンドを動かし、AWS CLI と Terraform でクラウドを操作する — ひととおりの土台ができた状態です。

次回はこの環境の上で、VS Code の WSL 拡張を使ったリモート開発や、Docker との連携あたりを扱えたらと思います。

出典一覧

すべて 2026年7月28日に確認しています。

WSL / 環境全般

WSL 開発環境を設定する — Microsoft Learn

Git

Node.js / nvm

pnpm

AWS CLI

Terraform

投稿日: 2026年7月28日

カテゴリ: 未分類

タグ:

coiai

この記事もおすすめ

「最新版を使えばいい」は本当に正しい？Dependabotを使って“pin + 自動更新”にする理由

依存ライブラリやGitHub Actions、Terraform Providerのバージョン管理をしていると、よく出てくるのが次の考え方です。新しいバージョンが出たら、常に最新版へ上げればいいのでは？一見すると合理的です。実際、古いバージョンを長期間使い続けるより、継続的にアップデートした方が、脆弱性や非互換の問題を後回しにしにくくなります。ただし、実際の開発運用では、「バージョンを固定しない」ことと「常に新しい状態を保つ」ことは別です。むしろ、バージョンは固定し、Dependabotで自動的に更新PRを作るという運用の方が、安全性と更新頻度を両立しやすくなります。今回は、実際の開発チームで出た「pinするべきか、しないべきか」という議論をベースに、Dependabotをどう使うべきか整理します。きっかけは「そもそもpinしなくていいのでは？」という疑問あるプロジェクトで、GitHub ActionsやTerraform Providerのバージョンを更新する話が出ました。その中で、理想的には何もpinしない方がいい。新しいバージョンが出たら常にアップグレードすればいいのでは？という意見が出ました。この考え方自体は間違っていません。目標としては、依存関係を古いまま放置しないというのが正しいです。ただし、その目標を実現する方法として「pinしない」を選ぶと、別の問題が出てきます。そこで出てきたのが、「pinしない」のではなく、「pin + automated bumps」にしようという考え方です。つまり、バージョンは固定する。しかし、更新作業は自動化する。これがDependabotを使う理由です。 GitHub Actionsでは、floating tagがリスクになるたとえばGitHub Actionsでは、次のような指定をすることがあります。これは分かりやすく、一般的な書き方です。ただし、v4 のようなタグは、厳密には「特定のコードそのもの」を表しているわけではありません。タグが別のコミットを指すように変更されれば、同じ @v4 という記述でも、実際に実行されるコードが変わる可能性があります。 CI/CDで実行されるActionは、ビルド環境やデプロイ権限にアクセスすることがあります。そのため、これはサプライチェーンセキュリティの観点でも重要です。より厳密に管理するなら、特定のコミットSHAに固定します。こうすると、同じ設定から実行されるコードが勝手に変わることはありません。ただし問題があります。固定しただけでは、そのバージョンは永遠に古くなっていきます。そこでDependabotを使います。新しいバージョンが出たら、という流れにします。つまり、固定することで再現性を確保し、Dependabotで鮮度を維持する […]

GMKtec EVO-X2にUbuntuを入れたら有線LANが認識されなかった話

オンプレミスAIサーバー(ローカルLLM + 社内文書RAG)の構築を始めました。機材はGMKtec EVO-X2、AMD Ryzen AI Max+ 395搭載のミニPCです。128GBのユニファイドメモリをGPUに大きく割り当てられるので、ローカルLLM用途では今いちばん面白いマシンだと思っています。この記事は初日の作業ログです。結論から言うと「インストールUSBが起動しない」「有線LANが認識されない」という2つの罠を踏んだので、同じ構成を組む方のために記録しておきます。 OSはLinuxかWindowsか最初に迷うのがここですが、サーバー用途ならUbuntu Server一択でした。日常操作はすべてブラウザ(Open WebUI)経由なので、サーバーOSにGUIは不要です。管理画面が欲しければCockpitを入れれば、Webブラウザからメトリクス確認・サービス再起動・ターミナルまで使えます。「CUIのサーバー + Web管理画面」が現代の標準形だと思います。 BIOS設定 ― EVO-X2で一番大事なのはVRAM割り当て電源ON直後にDel連打でBIOS(AMI)へ入ります。設定したのは3つです。罠その1: インストールUSBが起動しない Ubuntu Server 24.04のISOをMacから dd でUSBメモリに書き込み、いざブート……しません。Boot Overrideに出てくる「UEFI OS」を選んでもWindowsが立ち上がってしまいます。切り分けの過程が学びでした。原因はおそらく、dd の書き込みが完全に終わる前に抜いてしまったことです。dd は進捗表示が止まってからもバッファの書き出しが続くので、完了統計が表示されるまで待たなければいけません。パーティションテーブルはディスク先頭に書かれるため、途中で切れていても一見正常に見えるのが厄介なところです。教訓: インストールUSB作成はbalenaEtcherを使いましょう。書き込み後に自動でベリファイ(照合)まで走るので、「書けたつもり」が原理的に起きません。Etcherで書き直したら一発で起動しました。インストール時の選択罠その2: 有線LANが認識されないインストール完了、ログイン成功。しかし ip a を見ると有線LANにIPがありません。それどころか、よく見ると有線のインターフェース自体が存在しません。カーネルログを見て原因が確定しました。 EVO-X2の2.5GbEチップ(Realtek RTL8125D)が新しすぎて、Ubuntu 24.04の標準カーネル6.8のドライバが知らないチップだったのです。インストール中にネットに繋がらなかったのもこれが原因でした。ケーブルを何度挿し直しても無駄だったわけです。教訓: 「繋がらない」時はケーブルを疑う前に dmesg を読みましょう。カーネルログには大抵、答えがそのまま書いてあります。解決: HWEカーネル新しいチップに対応するには、新しいカーネルを入れれば解決します。Ubuntuには**HWE(Hardware […]

FSD v2.1 Feature-Sliced Design を導入する

この記事は何？公式のドキュメントやチュートリアル、exsample を読んで理解するのが一番いいですが、備忘録として残しておきます。特に後述の Skills, Steiger については開発する際にあった方が便利なので、それについても記事にします。 FSDとは？ FSD (Feature-Sliced Design) はフロントエンドのアーキテクチャの一つです。 FSDとは責務で分けていくアーキテクチャと違い、ページやエンティティで分けていくアーキテクチャというとわかりやすいと思います。コードの分離の仕方について話す前に、FSDで前提となるこの３つについて理解する必要があります。レイヤーより細かく分けていく方法がありますが、この記事では導入だけ触れたいので、３つのレイヤーのみ説明します。です。この流れは上（app）に向かえば向かうほどアプリケーション固有、下（shared）に向かうほど汎用的になります。原則として上位レイヤーは下位レイヤーを利用できるが、下位レイヤーから上位レイヤーへ依存できません。始め方としては小さく初めて、必要になったらレイヤーを増やしてくようです。スライスブログアプリであればレイヤーの pages にはといったページに分けられるため、このような構成になります。このblog-list, blog-detail, user がスライスです。これらはページやエンティティによって分けられます。セグメントこれらのmodel, ui といった部分がエンティティです。これらは責務にあたります。sharedに関しては直下にスライスではなくセグメントが入ります。 FSD 2.1 で重要なのは Pages First です。とにかくPagesから作って、細分化の必要ができたら、下位レイヤーに抽出します。 Steiger Steiger とはアーキテクチャリンターです。以下でインストールできます。 AIコーディングのために Claude Skills https://github.com/feature-sliced/skills?utm_source=chatgpt.com このリポジトリが公式に公開されています。これで Skills を追加できるので、claude にFSDの設計知識を共有できます。

フロントエンドのアーキテクチャについて最初から考える

これは何？この記事は基本に立ち戻りアーキテクチャの選定を試みた際の備忘録です。Feature-Sliced Design（FSD）や Vertical Slice Architecture など、モダンなアーキテクチャがありますが、どのような判断をもとに選定するのかを考え直します。アーキテクチャの地図アーキテクチャを理解するために、以下のような学習のための地図を作りました。設計原則、アーキテクチャ、個別の設計パターンへと詳細になっていきます。そもそも、、、このコードは何を担当しているのかを考えるのが最初の問です。商品一覧画面を作るときにといったタスクを書き出します。これら全てを一つの巨大なコンポーネントとして作ることもできますが、管理が大変になるのは皆さんもお分かりだと思います。参考：https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html?utm_source=chatgpt.com ここからどこまでを同じモジュールとして管理するのか？という設計の問題が始まります。 Cohesion と Coupling CohesionとCouplingはそれぞれ、凝集度、結合度というようです。https://qiita.com/dsudo/items/ee3fee1f558c7f1b359f Cohesionは関係するコードがまとまっているか？ Couplingは別のコードにどれだけ依存しているか？です。例えば以下のようなコードがあります。技術的な種類ごとに整理されていますが、商品一覧のコーディングをするのにそれぞれ別のディレクトリを行き来する必要があります。一方で、以下のように書いた場合はどうでしょうか？この書き方なら、商品に依存するコードがまとまっています。この書き方が Feature-based Architecture, Vertical Slice Architecture に繋がっていきます。コロケーションについて colocation Place code as close to where it’s relevant as possible 同じ種類のコードを集めることではなく、一緒に変更されるコードを近くに置くことです。 https://kentcdodds.com/blog/colocation?utm_source=chatgpt.com Layered Architecture についてここからアーキテクチャの話です。 Layered Architectureでは、技術的責務でアプリケーションを分離します。これのメリットは責務がわかりやすいところです。しかし、この方法では前述までとは変わり、機能を変更するときに、横断して変更する可能性があります。つまり、技術的には分かれている一方で、機能は複数に分散するわけです。 […]