学習環境セットアップ

目次

• 概要
• 基本方針
• OS別の入口
• ターミナル
• エディタ
• Git
• SSHとGitHub
• Node.jsとPython
• version manager
• ローカルサーバー
• Dockerとコンテナ
• 環境変数とsecret
• 環境を壊しにくくする
• プロジェクトごとの分離
• dotfilesと設定ファイル
• バックアップと同期
• トラブルシューティング
• セットアップ確認チェックリスト
• ツール選択の実践的ガイド
• バージョン管理の実践
• npm と Node.js エコシステム
• Python の仮想環境管理
• Docker による環境の統一
• Mise によるポリグロット開発
• CI/CD パイプラインの設計
• 開発環境のセキュリティ
• 開発環境のテンプレート化
• Docker開発環境の詳細仕様
• まとめ
• 参考文献

概要

学習環境は、コードを書く、実行する、調べる、記録するための土台です。最初から完璧に揃える必要はありませんが、ターミナル、エディタ、Git、Node.js、Python、ローカルサーバーを使えると、この教材の多くを手元で試せます。

基本方針

環境構築では、次を意識します。

• 公式インストーラや広く使われる方法を選ぶ
• projectごとに依存を分ける
• versionを確認する
• secretをファイルに直書きしない
• 手順をREADMEに残す
• 環境を再作成できるようにする
• global installを増やしすぎない

最初に揃えるものは多くありません。

環境構築で一番大事なのは、何を入れたかを記録することです。記録があれば、壊れても戻せます。

OS別の入口

OSによって、最初に詰まりやすい場所が違います。

macOSでは、開発toolの多くがCommand Line Toolsに依存します。

xcode-select --install

Windowsでは、Web/Unix系の学習にはWSL2を使うとLinuxに近い環境で学べます。ただし、Windows側とWSL側でファイルパスや改行、permissionの扱いが違うため、どちらで作業しているかを意識します。

wsl --install

Linuxでは、distributionごとのpackage managerを使います。

sudo apt update
sudo apt install git curl build-essential

この教材のような静的サイトやWeb系の学習では、macOS/Linux/WSL2のいずれかでterminalとGitとNode.jsが使える状態があれば十分に進められます。

ターミナル

ターミナルはCLIを使う入口です。

確認するコマンドです。

pwd
ls
whoami
echo "$SHELL"

macOSではzshが標準です。Linuxではbashが広く使われます。

よく使う基本コマンドです。

PATHの確認も重要です。

echo "$PATH"
which node
which python3

同じ node や python3 でも、どこにある実行ファイルかで挙動が変わります。version managerを使い始めると特に大事です。

エディタ

エディタは、コードとドキュメントを編集する場所です。重要なのは、見た目よりも次の機能です。

• syntax highlight
• file search
• grep
• terminal integration
• Git diff
• formatter
• language server

設定は少しずつ育てます。最初から拡張を入れすぎると、問題の原因を切り分けにくくなります。

最低限あると便利な設定です。

EditorConfigを置くと、editorが違っても基本設定をそろえやすくなります。

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

Git

Gitは変更履歴を管理します。

git --version
git config --global user.name
git config --global user.email

最初に覚えるコマンドです。

git status
git diff
git add .
git commit -m "初回コミット"

最初に設定しておくとよい項目です。

git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global core.editor "code --wait"

改行コードの扱いはOS差分が出やすいので、project側で .gitattributes を置くと安定します。

* text=auto
*.sh text eol=lf
*.bat text eol=crlf

日常的な確認の流れです。

SSHとGitHub

GitHubへpushするには、HTTPS tokenかSSH keyを使います。長く使うならSSH keyが便利です。

ssh-keygen -t ed25519 -C "your-email@example.com"

公開鍵を表示します。

cat ~/.ssh/id_ed25519.pub

GitHubに公開鍵を登録したら、接続確認します。

ssh -T git@github.com

秘密鍵は絶対に共有しません。GitHubに登録するのは .pub が付いた公開鍵です。

複数アカウントや会社/個人の鍵を分ける場合は ~/.ssh/config を使います。

Node.jsとPython

Node.jsは、フロントエンドやビルドスクリプトでよく使います。

node --version
npm --version

Pythonは、スクリプト、データ処理、簡易サーバーで便利です。

python3 --version
python3 -m venv .venv

projectごとに依存を分けると、環境が壊れにくくなります。

Node.jsでは、package.json とlockfileを中心に再現します。

npm ci
npm run build
npm test

npm install は依存追加や更新、npm ci はlockfileに従った再現性の高いinstallに向きます。CIや既存projectの再現では npm ci を使うことが多いです。

Pythonでは、venvをproject内に作ります。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

venvは移動やコピーではなく、作り直せるものとして扱います。.venv 自体はGitに入れません。

.venv/
node_modules/

version manager

複数projectを触るなら、version managerを使うと安定します。

project rootにversionを書いておくと、参加者が同じversionを使いやすくなります。

.node-version
.python-version
mise.toml

mise.toml の例です。

[tools]
node = "24"
python = "3.12"

version managerを使う場合は、which node、node --version、mise current のように、実際にどの実行ファイルが使われているかを確認します。

ローカルサーバー

静的サイトは、ファイルを直接開くよりローカルサーバーで確認する方が本番に近くなります。

python3 -m http.server 8000

アクセスします。

http://localhost:8000/

clean URL、module script、fetch、CORSなどは、file URLでは挙動が変わることがあります。

よく使うローカルサーバーです。

ブラウザではDevToolsも使います。

Dockerとコンテナ

Dockerは、projectごとの実行環境をcontainerとして分ける道具です。必須ではありませんが、DBや外部middlewareを含む学習では便利です。

docker --version
docker compose version

使いどころです。

Dockerで学習環境を作るときも、volume、port、env、secretの扱いを確認します。

services:
  db:
    image: postgres:16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: example

学習用のpasswordを本番と混ぜないことが大事です。Dockerは便利ですが、secret管理を不要にする道具ではありません。

環境変数とsecret

API key、token、passwordをコードに直書きしないようにします。

.env
.env.local
.env.example

.env.example はGitに入れてよい雛形です。

API_BASE_URL=https://example.com
API_TOKEN=

.env はsecretを含むためGitに入れません。

.env
.env.*
!.env.example

環境変数を使うときは、読み込み場所と必要な変数をREADMEに書きます。

`.env.example` を `.env` にコピーし、必要な値を設定してください。

環境を壊しにくくする

環境を壊しにくくするコツです。

問題が起きたら、まずversionとcurrent directoryを確認します。

pwd
node --version
python3 --version
git status

壊しにくい運用です。

clean installの例です。

rm -rf node_modules
npm ci

削除コマンドは慎重に使います。まず pwd で場所を確認します。

プロジェクトごとの分離

学習が進むと、複数のプロジェクトで違うversionのNode.js、Python、ライブラリを使うようになります。globalに全部入れると、あるプロジェクトの更新が別プロジェクトを壊すことがあります。

projectごとに分けると、影響を小さくできます。

方針です。

project scriptsを使うと、参加者が同じコマンドを実行できます。

{
  "scripts": {
    "build": "node build/build.js",
    "dev": "python3 -m http.server 8000 -d dist",
    "check": "npm run build"
  }
}

「このprojectで何を実行すればよいか」は、global toolの使い方ではなく package.json や Makefile、justfile に寄せると共有しやすくなります。

dotfilesと設定ファイル

shellやeditorの設定は便利ですが、増えすぎると環境構築の再現性が下がります。

個人のdotfilesとprojectの設定は分けます。projectに必要な設定はrepositoryに置き、個人の好みはdotfilesに置きます。

バックアップと同期

学習環境では、コードよりも「自分のメモ」「設定」「秘密鍵」を失うと痛いことがあります。

Gitにpushしていない変更は、そのPCにしかありません。作業の節目でcommit/pushする習慣をつけると安心です。

トラブルシューティング

環境構築のエラーは、場所、version、PATH、権限、networkに分けて見ると速いです。

調査の基本セットです。

pwd
git status
which node
node --version
which python3
python3 --version
echo "$PATH"

portを使っているprocessを確認する例です。

lsof -i :8000

「昨日は動いた」の多くは、cwd、version、依存、環境変数、networkのどれかが変わっています。変わったものを1つずつ戻して確認します。

セットアップ確認チェックリスト

新しい環境で確認することです。

• terminalが開ける
• editorでprojectを開ける
• Gitのuser name / emailが設定済み
• repositoryをcloneできる
• Node.js / npmのversionを確認できる
• Pythonのversionを確認できる
• buildが通る
• ローカルサーバーで確認できる
• .env.example から必要な設定が分かる
• secretをGitに入れていない
• which node / which python3 で想定の実行ファイルを指している
• lockfileから依存を再現できる
• SSH keyまたはtokenでpushできる
• editorのformat/diff/searchが使える
• browser DevToolsを開ける
• Dockerが必要なprojectでは docker compose version を確認できる

確認コマンド例です。

git status
node --version
npm --version
python3 --version
npm run build
python3 -m http.server 8000

セットアップ手順は、成功したあとにREADMEへ反映します。未来の自分や次に参加する人が、同じ罠に落ちなくなります。

ツール選択の実践的ガイド

開発環境構築には、多くのツール選択が必要です。各カテゴリでの推奨事項です。

エディタ・IDE の比較

VS Code の圧倒的なシェアは、拡張性とパフォーマンスの両立が理由です。

VS Code が支配的になった理由：

1. 統一された拡張機能: Language Server Protocol (LSP) 対応
2. リモート開発: SSH、Container、WSL で同じ環境
3. 統合ターミナル: エディタ内でシェルコマンド実行
4. デバッグ統合: DAP(Debug Adapter Protocol) による統一デバッグ

VS Code の推奨拡張機能

ms-vscode-remote.remote-ssh, ms-vscode.remote-explorer, esbenp.prettier-vscode, dbaeumer.vscode-eslint, ms-python.python, rust-lang.rust-analyzer などが推奨されます。

バージョン管理の実践

Git の使用が標準化されていますが、実装エラーは多く見られます。

Git ワークフロー の選択

• Centralized: main に全員がプッシュ（簡単だが品質管理困難）
• Feature Branching: feature/ で開発してPR（一般的、レビュー容易）
• Git Flow: develop, main, release/* で厳密管理（複雑、大規模チーム向け）
• Trunk-Based: main にほぼ毎日マージ、フィーチャーフラグで制御（CI/CD 向け、モダン）

GitHub での推奨: Feature Branching か Trunk-Based Development

Git のセットアップ チェックリスト

git config --global user.name "Your Name"
git config --global user.email "your@email.com"
git config --global core.editor "vim"
git config --global pull.rebase true

各リポジトリでの設定上書きも可能です。

EditorConfig の活用

EditorConfig.org の標準では、プロジェクト内でエディタ依存の設定を統一できます。

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true

[*.{js,ts}]
indent_style = space
indent_size = 2

[*.py]
indent_style = space
indent_size = 4

VS Code 含むほとんどのエディタが対応しており、チーム開発で形式の不統一を防ぎます。

npm と Node.js エコシステム

npm(Node Package Manager)は、npm.js の公式パッケージレジストリを使用します。

package.json の構造

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "jest"
  },
  "dependencies": {
    "react": "^18.2.0"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "jest": "^29.0.0"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

npm パッケージ管理

• npm install: package-lock.json に基づき正確にインストール
• npm ci: CI環境向け（再現性重視）
• npm audit: 脆弱性チェック
• npm audit fix: 自動修復

Python の仮想環境管理

Python では複数のバージョンと依存関係を管理する必要があります。

venv vs Poetry vs pyenv

推奨セットアップ（2024年）

pyenv install 3.12.0
pyenv local 3.12.0
poetry init
poetry add requests
poetry install
poetry run pytest

requirements.txt の Pin 戦略

requests==2.31.0
django==4.2.0
gunicorn==21.2.0

すべてのバージョンを Pin することで、再現性を確保します。

Docker による環境の統一

Docker コンテナは、開発環境の完全な再現を実現します。

基本的な Dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

docker-compose での開発環境

version: '3.9'
services:
  app:
    build: .
    volumes:
      - .:/app
    ports:
      - "5000:5000"
  db:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

Mise によるポリグロット開発

Mise.jdx.dev は、複数言語のバージョン管理を一元化できます。

[tools]
python = "3.11.0"
node = "20.0.0"
golang = "1.21.0"
rust = "1.70.0"

このアプローチは、マイクロサービスでの開発効率を大幅に向上させます。

CI/CD パイプラインの設計

GitHub Actions は、リポジトリの .github/workflows/ で定義できます。

基本的な CI パイプライン

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.10, 3.11, 3.12]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
      - run: pip install -r requirements-dev.txt
      - run: pytest --cov
      - run: mypy .

このパイプラインは複数 Python バージョンでテスト、カバレッジ計測、型チェックを実行します。

開発環境のセキュリティ

しばしば見落とされるセキュリティ面です。

シークレット管理

DATABASE_URL=postgresql://...
API_KEY=sk-...
SECRET_KEY=...

.env ファイルで管理し Git から除外します。GitHub Secrets で CI に注入します。

依存関係の脆弱性チェック

npm audit
pip-audit
cargo audit

GitHub Dependabot による自動チェックも推奨されます。

開発環境のテンプレート化

新しいプロジェクトを迅速に開始するため、テンプレートを用意します。

npx create-react-app my-app
npx create-next-app@latest
pipx install cookiecutter
cargo new my-project

これらはプロジェクト構造、依存関係、設定ファイルをテンプレートから自動生成します。

Docker開発環境の詳細仕様

Docker構成は、開発環境・ビルド環境・本番環境を統一します。実装レベルのベストプラクティスを整理します。

マルチステージビルドの効率化

本番イメージサイズを削減するため、ビルド専用ステージを分離します。

# ステージ1: ビルド環境
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
RUN npm run build

# ステージ2: 実行環境（軽量）
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json .
EXPOSE 3000
CMD ["node", "dist/index.js"]

効果: ビルド専用パッケージ（webpack, typescript等）が本番イメージに含まれない

# ビルド
docker build -t myapp .

# イメージサイズの確認
docker images myapp
# REPOSITORY  TAG      IMAGE ID     SIZE
# myapp       latest   abc123       150MB  (ビルド用含まず)

docker-composeのネットワーク管理

複数サービス間通信を効率的に管理します。

version: '3.9'

services:
  web:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DB_HOST=postgres  # サービス名で解決
      - DB_PORT=5432
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - app-network

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=mydb
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - app-network
    volumes:
      - postgres_data:/var/lib/postgresql/data

networks:
  app-network:
    driver: bridge

volumes:
  postgres_data:

重要: depends_on の condition: service_healthy で、サービスの完全起動を待機

# Python: PostgreSQL接続確認
import psycopg2
import os

try:
    conn = psycopg2.connect(
        host=os.getenv('DB_HOST', 'localhost'),
        port=int(os.getenv('DB_PORT', 5432)),
        database=os.getenv('POSTGRES_DB'),
        user=os.getenv('POSTGRES_USER'),
        password=os.getenv('POSTGRES_PASSWORD')
    )
    print("DB接続成功")
    conn.close()
except psycopg2.OperationalError as e:
    print(f"DB接続失敗: {e}")

.dockerignore によるビルド最適化

不要なファイルをビルドコンテキストから除外します。

# .dockerignore
node_modules
npm-debug.log
.git
.gitignore
README.md
.env.local
.env.*.local
coverage
dist
build
__pycache__
*.pyc
.pytest_cache
.vscode
.idea
*.swp
*.swo

効果: ビルドコンテキストサイズを削減し、キャッシュヒット率を向上

# ビルドコンテキストサイズの確認
docker build --no-cache -t myapp . 2>&1 | grep "Sending build context"
# Sending build context to Docker daemon  150MB

Mise による複数バージョン共存

Mise（旧asdf）は、言語ごとに異なるバージョンを効率的に管理します。

# .mise.toml
[env]
# グローバル環境変数
NODE_ENV = "development"

[tools]
# Node.js
node = "20.10.0"
# Python
python = "3.12.0"
# Rust
rust = "1.75.0"
# Go
go = "1.21.5"
# Ruby
ruby = "3.3.0"

[tasks]
# タスク定義
build = "npm run build"
test = "npm test"
dev = "npm run dev"

セットアップ:

# Mise インストール
curl https://mise.jdx.dev/install.sh | sh

# プロジェクトディレクトリで初期化
mise install

# バージョン確認
mise versions
# node  20.10.0
# python 3.12.0

# タスク実行
mise run build
mise run test

editorconfig での言語間コード規約統一

異なるエディタ間で、インデント・改行・エンコーディングを統一します。

# .editorconfig
root = true

# すべてのファイル
[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

# Python
[*.py]
indent_style = space
indent_size = 4

# JavaScript/TypeScript
[*.{js,ts,jsx,tsx}]
indent_style = space
indent_size = 2

# JSON/YAML
[*.{json,yaml,yml}]
indent_style = space
indent_size = 2

# Makefile（タブ必須）
[Makefile]
indent_style = tab

# Markdown（末尾空白保持）
[*.md]
trim_trailing_whitespace = false

エディタ側の設定:

// VS Code: .vscode/settings.json
{
  "editorconfig.enable": true,
  "files.insertFinalNewline": true,
  "files.trimTrailingWhitespace": true,
  "files.eol": "\n"
}

npm の依存関係固定化戦略

package-lock.json を用いた再現可能なセットアップ:

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

セマンティックバージョニング:

• "express": "4.18.2" - 完全固定（推奨：本番）
• "express": "^4.18.0" - マイナーアップデート許可（^）
• "express": "~4.18.0" - パッチアップデート許可（~）
• "express": "*" - 任意バージョン（非推奨）

# package-lock.json で依存関係をロック
npm ci  # 推奨：ci = clean install （ロック版）
npm install  # 開発時：最新パッチを取得

# 依存関係の監査
npm audit
npm audit fix
npm audit fix --audit-level=high

Python Poetry による環境管理

# pyproject.toml
[tool.poetry]
name = "myproject"
version = "0.1.0"
description = "A sample project"
authors = ["Your Name <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.104.0"
sqlalchemy = "^2.0.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
black = "^23.0.0"
pylint = "^3.0.0"

[tool.black]
line-length = 88

[tool.pytest.ini_options]
testpaths = ["tests"]

セットアップ:

# 環境構築
poetry install

# 依存パッケージ追加
poetry add fastapi
poetry add pytest --group dev

# 仮想環境有効化
poetry shell

# コマンド実行
poetry run pytest

GitHub SSH キーペアの設定（開発環境の必須ステップ）

# SSH キー生成（推奨: Ed25519）
ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/id_ed25519

# または RSA（互換性重視）
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# SSH キーを ssh-agent に追加
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# ~/.ssh/config での設定
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
  AddKeysToAgent yes
  IdentitiesOnly yes

# 接続確認
ssh -T git@github.com
# Hi username! You've successfully authenticated...

開発環境の隔離（venv vs Poetry vs Conda）

推奨: pyenv + Poetry の組み合わせ

# pyenv: Python 3.12 を環境に導入
pyenv install 3.12.0
pyenv local 3.12.0  # プロジェクト固定

# Poetry: 依存パッケージをロック
poetry install
poetry run python --version  # Python 3.12.0

GitHub Actions によるCI環境

# .github/workflows/test.yml
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.11, 3.12]
    
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v4
        with:
          python-version: \${{ matrix.python-version }}
      
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install poetry
          poetry install
      
      - name: Run tests
        run: poetry run pytest
      
      - name: Run linter
        run: poetry run pylint src/

まとめ

学習環境は、試行錯誤を速くするための土台です。ターミナル、エディタ、Git、Node.js、Python、ローカルサーバーを最小限そろえ、versionと手順を記録しておくと、学習も開発も安定します。慣れてきたら、version manager、Docker、.env.example、EditorConfig、READMEのセットアップ手順を整え、壊れても再作成できる環境にしていきます。

参考文献

公式・標準

• MDN Web Docs: Local testing server
• Python Documentation
• Python Documentation: venv
• npm Docs
• npm Docs: About npm

解説・補助

• Pro Git: First-Time Git Setup
• Docker Docs: Get Docker
• Node.js Documentation
• Git Documentation
• mise Documentation
• Visual Studio Code Documentation
• GitHub Docs: Connecting to GitHub with SSH
• EditorConfig