macOSでColima（Docker Desktop代替）を使用し、Rails 8.1の最新環境で「Hello World」REST APIを構築する完全手順書です。

※ 調査した内容、実際に行った手順をClaudeに渡して記事化しております。

前提条件

macOS（Apple Silicon または Intel）
Homebrew がインストール済み

構築する環境

OS: macOS
コンテナランタイム: Colima（Docker Desktop代替）
Ruby: 3.4.7
Rails: 8.1.0
Database: PostgreSQL 16
API: REST API（Hello World エンドポイント）

環境構築手順

ステップ1: Homebrewで開発ツールをインストール

# Colima, Docker CLI, Docker Composeをインストール
brew install colima docker docker-compose

# Docker CLIプラグインの設定
mkdir -p ~/.docker
cat > ~/.docker/config.json <<'JSON'
{
  "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"]
}
JSON

Intel Macの場合の注意点:
/opt/homebrewは/usr/localに読み替えてください。

ステップ2: Colimaの初回起動と設定

Apple Siliconの場合

# Colimaの初回起動（Apple Silicon推奨設定）
colima start --cpu 4 --memory 8 --disk 60 --arch aarch64 --vm-type=vz --mount-type=virtiofs

# Docker contextの確認
docker context use colima
docker context show
# => colima と表示されればOK

Intel Macの場合

colima start --cpu 4 --memory 8 --disk 60 --vm-type=vz --mount-type=virtiofs

Colimaの停止

colima stop

ステップ3: brew servicesにColimaを登録（自動起動設定）

Colimaをログイン時に自動起動させるには、brew servicesを使用します。

# Colimaをbrew servicesに登録
brew services start colima

# サービスの状態確認
brew services list | grep colima
# => colima started ... と表示されればOK

# Colimaの動作確認
colima status
# => colima is running と表示されればOK

重要な注意点:

brew services start colimaは通常ユーザーで実行してください（sudoを使わない）
brew servicesで起動した場合、初回起動時の--cpuや--memoryなどのオプションは適用されません
オプションをカスタマイズしたい場合は、事前にcolima start --editで設定ファイルを編集してください

Colima設定のカスタマイズ（オプション）

# 設定ファイルを開く
colima start --edit

# 以下の設定を編集
# cpu: 4
# memory: 8
# disk: 60
# arch: aarch64  # Intel Macの場合は x86_64
# vmType: vz
# mountType: virtiofs

設定後、一度Colimaを再起動します。

colima stop
brew services restart colima

brew servicesからColimaを削除する場合

brew services stop colima

ステップ4: プロジェクトディレクトリ作成

# プロジェクトディレクトリを作成
mkdir -p ~/projects/rails-hello-api
cd ~/projects/rails-hello-api

ステップ5: Dockerfile作成

cat > Dockerfile <<'EOF'
FROM ruby:3.4-slim

# 必要なパッケージをインストール
RUN apt-get update -y && apt-get install -y --no-install-recommends \
    build-essential \
    git \
    curl \
    pkg-config \
    nodejs \
    libpq-dev \
    libyaml-dev \
  && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# 環境変数を設定（PATHを先に設定）
ENV GEM_HOME=/usr/local/bundle \
    BUNDLE_PATH=/usr/local/bundle \
    BUNDLE_BIN=/usr/local/bundle/bin \
    PATH="/usr/local/bundle/bin:${PATH}"

# Bundler と Rails をインストール
RUN gem update --system && \
    gem install bundler -v "~> 2.5" && \
    gem install rails -v "~> 8.1"

EXPOSE 3000

# 非ログインシェルを使用
CMD ["bash", "-c", "bundle check || bundle install && bin/rails s -b 0.0.0.0 -p 3000"]
EOF

重要なポイント:

bash -c を使用（bash -lc は使わない）
libyaml-dev を明示的にインストール
ENV PATH を gem install より前に設定

ステップ6: docker-compose.yml作成

cat > docker-compose.yml <<'EOF'
services:
  app:
    build: .
    image: rails-hello-api:latest
    volumes:
      - .:/app:cached
      - bundle_data:/usr/local/bundle
    ports:
      - "3000:3000"
    environment:
      RAILS_ENV: development
      DATABASE_URL: postgresql://postgres:postgres@db:5432/rails_hello_api_development
    depends_on:
      - db
    command: bash -c "bundle check || bundle install && bin/rails s -b 0.0.0.0 -p 3000"

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: rails_hello_api_development
    ports:
      - "5433:5432"
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:
  bundle_data:
EOF

重要なポイント:

version: 行なし（Compose v2対応）
bundle_data ボリュームで gem を永続化
-b 0.0.0.0 でバインド

ステップ7: 初期Gemfile作成

cat > Gemfile <<'EOF'
source "https://rubygems.org"

ruby "~> 3.4.0"
EOF

touch Gemfile.lock

ステップ8: Dockerイメージをビルド

# イメージをビルド
docker compose build --no-cache

# ビルド確認
docker images | grep rails-hello-api

ステップ9: Railsプロジェクト生成

# Rails new を実行
docker compose run --rm app bash -c 'rails new . --api --force --database=postgresql --skip-git'

# Gemfileが生成されたか確認
cat Gemfile | head -20

重要なポイント:

bundle add rails は不要
rails new が全てのファイルを生成

ステップ10: 依存関係をインストール

# bundle install（永続化ボリュームに保存される）
docker compose run --rm app bash -c 'bundle install'

# インストール確認
docker compose run --rm app bash -c 'bundle check'
# => "The Gemfile's dependencies are satisfied" と表示されればOK

# Rails version確認
docker compose run --rm app bash -c 'rails -v'
# => "Rails 8.1.0" と表示されればOK

ステップ11: データベース設定

# database.ymlを更新
docker compose run --rm app bash -c "cat > config/database.yml <<'YAML'
default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= ENV.fetch(\"RAILS_MAX_THREADS\") { 5 } %>
  host: db
  username: postgres
  password: postgres

development:
  <<: *default
  database: rails_hello_api_development

test:
  <<: *default
  database: rails_hello_api_test

production:
  <<: *default
  database: rails_hello_api_production
YAML"

# データベース準備
docker compose run --rm app bash -c 'bin/rails db:prepare'

ステップ12: Hello World エンドポイント作成

# ルーティング設定
docker compose run --rm app bash -c "cat > config/routes.rb <<'RUBY'
Rails.application.routes.draw do
  get '/health', to: 'health#index'
  get '/hello', to: 'hello#world'
  get 'up' => 'rails/health#show', as: :rails_health_check
end
RUBY"

# HealthController作成
docker compose run --rm app bash -c "cat > app/controllers/health_controller.rb <<'RUBY'
class HealthController < ApplicationController
  def index
    render json: { 
      status: 'ok',
      timestamp: Time.current,
      rails_version: Rails.version,
      ruby_version: RUBY_VERSION
    }
  end
end
RUBY"

# HelloController作成
docker compose run --rm app bash -c "cat > app/controllers/hello_controller.rb <<'RUBY'
class HelloController < ApplicationController
  def world
    render json: { 
      message: 'Hello World from Rails 8.1!',
      app: 'rails-hello-api',
      environment: Rails.env
    }
  end
end
RUBY"

重要なポイント:

ルーティングは draw do ... end ブロック内に記述

ステップ13: アプリケーション起動

# アプリケーション起動
docker compose up -d

# ログ確認（起動完了まで待つ）
docker compose logs -f app

「Listening on http://0.0.0.0:3000」と表示されたら Ctrl+C でログ表示を終了。

ステップ14: 動作確認

# ヘルスチェック
curl http://localhost:3000/health

# Hello World
curl http://localhost:3000/hello

# Rails 8.1 ビルトインヘルスチェック
curl http://localhost:3000/up

期待される出力:

/health

{
  "status": "ok",
  "timestamp": "2025-10-26T...",
  "rails_version": "8.1.0",
  "ruby_version": "3.4.7"
}

/hello

{
  "message": "Hello World from Rails 8.1!",
  "app": "rails-hello-api",
  "environment": "development"
}

/up

ok

環境の完全初期化手順

既存の環境を削除して、最初からやり直す場合：

# プロジェクトディレクトリに移動
cd ~/projects/rails-hello-api

# すべてのコンテナ・イメージ・ボリュームを削除
docker compose down -v --rmi all

# 特定のボリュームを完全削除
docker volume rm rails-hello-api_db_data 2>/dev/null || true
docker volume rm rails-hello-api_bundle_data 2>/dev/null || true

# 生成されたRailsファイルを削除
rm -rf .github .kamal .rubocop.yml script app bin config db lib log public storage test tmp vendor .git
rm -f .dockerignore .gitattributes .gitignore .ruby-version Gemfile Gemfile.lock Rakefile config.ru README.md

# Dockerfile と docker-compose.yml のみが残る
ls -la

# ステップ5から再実行

日常的な操作コマンド Memo

# アプリケーション起動
docker compose up -d

# アプリケーション停止
docker compose down

# ログ確認
docker compose logs -f app

# Railsコンソール
docker compose exec app bash -c 'bin/rails console'

# コンテナ内でシェルに入る
docker compose exec app bash

# データベースマイグレーション
docker compose exec app bash -c 'bin/rails db:migrate'

# Gemfile変更時
docker compose run --rm app bash -c 'bundle install'
docker compose restart app

# ルーティング確認
docker compose exec app bash -c 'bin/rails routes'

# テスト実行
docker compose exec app bash -c 'bin/rails test'

# データベースリセット
docker compose run --rm app bash -c 'bin/rails db:reset'

# コンテナ状態確認
docker compose ps

トラブルシューティング

エラー: `rails: command not found`

原因: PATH が正しく設定されていない

解決策:

Dockerfile で bash -c を使用（bash -lc は使わない）
ENV PATH を gem install より前に設定

エラー: `yaml.h not found`

原因: libyaml-dev が不足

解決策:

RUN apt-get install -y libyaml-dev

エラー: gem が見つからない

原因: bundle_data ボリュームが永続化されていない

解決策:

volumes:
  - bundle_data:/usr/local/bundle

データベース接続エラー

原因: データベースコンテナが起動していない

解決策:

docker compose up -d db
docker compose logs db

Colimaが起動しない

原因: Docker Desktopなど他のDocker環境が動作している

解決策:

# Docker Desktopを完全に終了してから再度試す
colima delete
colima start --cpu 4 --memory 8 --disk 60 --arch aarch64 --vm-type=vz --mount-type=virtiofs

brew servicesでColimaが起動しない

原因: 設定ファイルに問題がある、または初回起動が必要

解決策:

# まず手動で一度起動
colima start --cpu 4 --memory 8 --disk 60 --arch aarch64 --vm-type=vz --mount-type=virtiofs
colima stop

# その後brew servicesに登録
brew services start colima

構成図

macOS (Host OS)
├── Homebrew管理
│   ├── Colima（Docker runtime）
│   ├── Docker CLI
│   └── Docker Compose
│
└── プロジェクト (~/projects/rails-hello-api)
    ├── Dockerfile（Ruby 3.4 + Rails 8.1）
    ├── docker-compose.yml
    ├── app/（Railsコード）← ホストで編集
    ├── db/（PostgreSQL 16コンテナ）
    └── bundle_data/（gemの永続化）

参考資料

まとめ

この環境構築ガイドでは、以下を実現しました。

Docker DesktopなしでColimaを使用したコンテナ環境
brew servicesによるColima自動起動設定
Rails 8.1 + PostgreSQL 16での環境設定
macOS最適化された設定（virtiofs, vz）

久しぶりのmacosでの開発環境構築だったので、備忘録として残しています。