Go to Qiita Advent Calendar Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kopug(Masahiro Funakoshi)

Rails 8.1 + Colima + Docker 環境構築の備忘録

Posted at

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の永続化）

参考資料

まとめ

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

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

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

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?