생성 · 구조 · 실행 · 삽질 해결까지 한 번에 정리
Ruby on Rails 예시 애플리케이션을 완전히 처음부터 직접 만들면서
마주쳤던 문제들과 해결 과정을 한 번에 정리해두었습니다.
“rails new 한 줄이면 끝”이라는 말이
안 통할 때를 대비한 실전 가이드입니다.
1. 프로젝트 개요
이 프로젝트는 Rails의 핵심 개념을 빠르게 익히기 위한 예시 애플리케이션입니다.
구현 기능
•
홈 페이지 (환영 메시지 + 현재 시간)
•
소개 페이지 (프로젝트 구조 설명)
•
게시글 CRUD (Create / Read / Update / Delete)
Rails의 MVC 구조, RESTful 라우팅, Convention over Configuration을
최소한의 코드로 경험하는 것이 목적입니다.
2. 생성된 프로젝트 구조
260111_2333_rails/
├── app/
│ ├── controllers/
│ │ ├── application_controller.rb
│ │ ├── home_controller.rb
│ │ └── posts_controller.rb
│ ├── models/
│ │ ├── application_record.rb
│ │ └── post.rb
│ ├── views/
│ │ ├── layouts/application.html.erb
│ │ ├── home/
│ │ │ ├── index.html.erb
│ │ │ └── about.html.erb
│ │ └── posts/
│ │ ├── index.html.erb
│ │ ├── show.html.erb
│ │ ├── new.html.erb
│ │ └── edit.html.erb
│ └── assets/config/manifest.js
├── config/
│ ├── application.rb
│ ├── boot.rb
│ ├── database.yml
│ ├── routes.rb
│ ├── webpacker.yml
│ └── environments/
│ ├── development.rb
│ ├── production.rb
│ └── test.rb
├── db/migrate/
│ └── 20240111000001_create_posts.rb
├── bin/rails
├── Gemfile
├── Gemfile.lock
├── Rakefile
└── README.md
Plain Text
복사
3. Rails 핵심 개념 요약
MVC 패턴
•
Model: 데이터와 비즈니스 로직 (app/models)
•
View: 사용자 화면 (app/views)
•
Controller: 요청 처리 및 흐름 제어 (app/controllers)
Convention over Configuration
Rails는 “관례”를 따르면 설정이 거의 필요 없습니다.
예를 들어:
•
PostsController → /posts
•
Post 모델 → posts 테이블
•
index 액션 → views/posts/index.html.erb
RESTful 라우팅
resources:posts
Ruby
복사
위 한 줄로 자동 생성되는 라우트:
HTTP | URL | Action |
GET | /posts | index |
GET | /posts/new | new |
POST | /posts | create |
GET | /posts/:id | show |
GET | /posts/:id/edit | edit |
PATCH | /posts/:id | update |
DELETE | /posts/:id | destroy |
4. 주요 파일 설명
routes.rb
Rails.application.routes.drawdo
root'home#index'
get'about',to:'home#about'
resources:posts
end
Ruby
복사
모델 (Post)
•
title: 필수, 3~100자
•
content: 필수
뷰(View)
•
ERB 템플릿 사용
•
application.html.erb에서 공통 레이아웃 관리
5. 설치하면서 실제로 겪은 문제들 & 해결 방법
Rails는 환경 의존성이 강해서,
“왜 안 되지?” 구간이 반드시 한 번은 옵니다.
아래는 실제로 마주친 문제들입니다.
① Ruby 버전 불일치
Your Ruby version is 3.4.7, but your Gemfile specified 3.2.0
Plain Text
복사
해결
ruby'>= 3.2.0'
Ruby
복사
② pkg-config 누락 (sqlite3 빌드 실패)
brew install pkg-config
Bash
복사
③ Bundler 누락
gem install bundler
Bash
복사
④ Puma 5 
Rack 3 충돌 (Rails 7.2)
gem'puma','~> 6.0'
Ruby
복사
bundle update puma
Bash
복사
⑤ 필수 파일 누락 이슈 모음
Rakefile
require_relative"config/application"
Rails.application.load_tasks
Ruby
복사
bin/rails
#!/usr/bin/env ruby
APP_PATH =File.expand_path('../config/application', __dir__)
require_relative'../config/boot'
require'rails/commands'
Ruby
복사
chmod +x bin/rails
Bash
복사
environments 설정 파일
•
development.rb
•
production.rb
•
test.rb
(없으면 Rails가 바로 죽습니다)
assets manifest
//= link_tree ../images
//= link_directory ../stylesheets .css
//= link_directory ../javascripts .js
JavaScript
복사
webpacker.yml 누락
•
config/webpacker.yml
•
app/javascript/packs/application.js
⑥ Rails 명령어가 안 먹힐 때
Rails is not currently installed on this system.
Plain Text
복사
항상 bundle exec 사용bundleexec rails s
# 또는
./bin/rails s
Bash
복사
6. 최종 실행 순서
bundle install
bundleexec rails db:create
bundleexec rails db:migrate
bundleexec rails server
Bash
복사
접속:
http://localhost:3000
Plain Text
복사
7. 체크리스트 (이거 안 하면 반드시 터짐)
•
Ruby 버전 확인
•
pkg-config 설치
•
Bundler 설치
•
Puma 6 이상
•
Rakefile 존재
•
bin/rails 실행 가능
•
environments 파일 3종
•
assets manifest
•
webpacker 설정
•
bundle exec 사용마무리하며
Rails는 “한 번 세팅되면 정말 빠른데”,
그 한 번이 생각보다 험난합니다.
그래도 이 과정을 한 번 겪고 나면:
•
Rails 구조가 눈에 들어오고
•
에러 메시지가 무섭지 않아지고
•
“아 이건 환경 문제구나” 감이 옵니다
이 글이 Rails 처음 만지는 분들이나
오랜만에 다시 잡은 분들께 도움이 되면 좋겠습니다.
안녕하세요
•
관련 기술 문의와 R&D 공동 연구 사업 관련 문의는 “glory@keti.re.kr”로 연락 부탁드립니다.
Hello
•
For technical and business inquiries, please contact me at “glory@keti.re.kr”