once-campfire 딥다이브
— 메시지 한 줄로 배우는 실시간 웹의 설계

1프로젝트 한줄 요약

Campfire는 방·개인 대화·파일 공유·검색·브라우저 알림·봇 연동을 갖춘 웹 채팅 애플리케이션입니다. 저장소 이름은 once-campfire이고 제품 이름은 Campfire입니다. 한 조직이 자기 서버에서 운영하는 구성이 중심이며, 운영 가이드도 여러 고객 조직을 완전히 분리하려면 인스턴스를 각각 배포하도록 설명합니다.

공부할 때는 기능 목록보다 메시지의 이동 경로를 보세요. 메시지 하나를 따라가면 저장·화면 갱신·접근 권한·검색·비동기 작업이 하나의 제품 안에서 연결되는 모습을 배울 수 있습니다.

1-1. 사용자에게 보이는 기능과 코드의 연결

1-2. 이 글을 읽는 데 필요한 출발점

HTML의 태그, HTTP 요청과 응답, 데이터베이스의 행과 기본 키 정도를 알고 있으면 시작할 수 있습니다. Ruby를 처음 접한다면 class는 객체의 설계도, def는 메서드 정의, include는 기능 모듈을 섞는 문법으로 읽으세요. Rails의 짧은 선언은 그 뒤에서 어떤 SQL과 콜백을 실행하는지까지 생각해야 이해됩니다.

# app/models/message.rb의 관계 선언 발췌
belongs_to :room, touch: true
belongs_to :creator, class_name: "User", default: -> { Current.user }
has_rich_text :body

# 뜻: 방에 속하고, 기본 작성자는 현재 사용자이며, 본문은 서식 있는 글이다.
# touch: true는 연결된 방의 갱신 시각도 바꾼다는 뜻이다.

2왜 주목받는가

2-1. 구독 없는 채팅이라는 방향이 코드와 연결됩니다

GitHub 설명은 “구독 없이 쓰는 아주 단순한 그룹 채팅”을 내세웁니다. MIT 라이선스로 코드를 읽고 수정할 수 있고, docs/self-hosting.md는 Docker 이미지와 영구 볼륨으로 직접 운영하는 절차를 설명합니다. 매달 서비스 사용료를 내는 모델과는 다른 소유·운영 방식입니다. 다만 서버 비용, 백업, 업데이트에 드는 노력까지 없어지는 것은 아닙니다.

선정 시점의 위치는 GitHub Trending Ruby Monthly #5입니다. 순위만으로 실제 유입 경로나 인기 상승의 원인을 증명할 수는 없습니다. 여기서 주목할 이유로 보는 것은 완성된 채팅 제품의 코드를 작은 단위로 추적할 수 있다는 학습 가치입니다.

2-2. Slack과 비교하면 강점의 방향이 보입니다

Slack의 채널과 연동 설명은 Slack 공식 소개를 기준으로 합니다. 요금이나 전체 기능의 우열을 비교하는 표는 아닙니다. Campfire의 장점은 이 목적에서 대화 도구의 내부를 이해하고 자기 요구에 맞게 바꿀 수 있다는 점입니다.

이 저장소의 매력은 기능의 개수보다, 한 서비스를 이해하는 데 필요한 코드와 운영 설정이 함께 있다는 데 있습니다. 모노리스 구조여서 컨트롤러와 모델, 화면, 배포 구성을 같은 저장소에서 이어 읽을 수 있습니다.

2-3. “단순한 채팅”에도 고급 설계가 숨어 있습니다

• 빠른 입력 경험: 서버 응답 전에 임시 메시지를 그린 뒤, 실제 메시지와 연결합니다.
• 권한의 수명: 한 번 방을 열었던 사람도 회원 자격이 사라지면 실시간 스트림에 다시 접근할 수 없어야 합니다.
• 검색의 정확성: 본문 저장만 성공하고 검색 색인 저장이 실패하는 상태를 피합니다.
• 성능과 안전: 캐시를 쓰더라도 사용자와 세션, 방 접근 검사를 생략하지 않도록 구성합니다.

2-4. README의 성능 표는 어떻게 읽어야 할까요?

README.md에는 Rails 외 여러 언어 구현과의 비교가 있습니다. Rails 열은 방 페이지 4,101요청/초, 메시지 쓰기 330요청/초를 기재합니다. 조건은 Ryzen AI MAX+ 395·RAM 32GB, 애플리케이션당 하드웨어 코어 4개, 동시 클라이언트 16개입니다. 이 수치를 모든 서버의 예상 처리량으로 바꾸어 읽으면 안 됩니다.

또한 bench/README.md가 설명하는 저장소 내 HTTP 비교 도구는 한 Puma 작업자·스레드 5개를 사용하고, Thruster·TLS·gzip을 측정에서 제외합니다. README의 다른 구현 비교와 로컬 최적화 도구의 측정 조건을 같은 것으로 간주하지 마세요. 이 수치는 README의 보고값이며, 임의의 배포 환경에 대한 처리량 보장이 아닙니다.

3기술 스택 전체 지도

3-1. 백엔드: Ruby와 Rails가 흐름을 묶습니다

버전의 기준은 .ruby-version, Gemfile, Gemfile.lock입니다. Gemfile은 허용 범위와 가져올 위치를 선언하고, 잠금 파일은 구체적으로 선택된 버전과 Git 리비전을 기록합니다. 예를 들어 puma ~> 8.0과 실제 선택된 8.0.2는 서로 다른 정보입니다.

Rails는 Gemfile에서 rails/rails의 main을 지정하지만, 잠금 파일은 e3d5c569d217c56c022b04acb127a8c24dbe9685를 가리킵니다. config/application.rb도 config.load_defaults 8.2를 사용합니다. 따라서 “최신 Rails 안정판 예제”로 읽기보다 특정 개발 리비전에 묶인 애플리케이션으로 읽어야 합니다.

3-2. 프론트엔드: HTML을 중심으로 작은 동작을 붙입니다

표의 Turbo Rails와 Stimulus Rails 버전은 Rails 통합 젬의 버전입니다. 브라우저용 Turbo·Stimulus의 독립 패키지 버전과 혼동하지 마세요. Highlight.js는 config/importmap.rb에 실제 연결된 벤더 파일을 기준으로 읽으세요.

package.json은 없고, app/javascript/application.js가 Turbo와 초기화 코드, 컨트롤러를 불러옵니다. 모듈 이름을 실제 파일 URL에 연결하는 곳은 Importmap입니다. 화면의 기본 모양은 서버가 만들고, 입력·스크롤·임시 표시 같은 상호작용은 브라우저의 작은 모듈들이 맡습니다.

예를 들어 app/javascript/controllers/composer_controller.js는 전송과 초안 저장을, app/javascript/controllers/messages_controller.js는 새 메시지와 임시 메시지의 정리를 맡습니다. app/javascript/models/message_paginator.js는 이전·다음 페이지를 가져옵니다. HTML 중심 구조에도 JavaScript는 필요하며, 역할을 나누는 방식이 핵심입니다.

3-3. 인프라·빌드: 하나의 이미지 안에 여러 프로세스

# Procfile 발췌
web: bundle exec thrust bin/start-app
redis: redis-server config/redis.conf
workers: FORK_PER_JOB=false INTERVAL=0.1 bundle exec resque-pool

# Dockerfile에서 확인하는 큰 단계
Ruby 4.0.7 slim
  → 시스템 패키지 설치
  → 별도 build 단계에서 bundle install, assets:precompile
  → 최종 이미지에 젬과 애플리케이션 복사
  → UID 1000 사용자로 bin/boot 시작

bin/boot의 ProcessMonitor는 Procfile을 읽고 각 프로세스를 시작하며 종료 신호를 전달합니다. 웹 앞단의 Thruster 0.1.23은 thrust 명령으로 연결됩니다. bin/start-app은 남은 PID 파일을 지우고 db:prepare 후 Rails 서버를 시작합니다.

Docker에는 curl, libsqlite3-0, libvips, libjemalloc2, ffmpeg, redis가 설치됩니다. 이 운영체제 패키지들은 설치 명령에 버전이 고정되어 있지 않습니다. Redis 젬 5.4.1을 Redis 서버 버전이라고 쓰면 안 됩니다. 개발용 bin/setup의 Redis 이미지는 redis:7이고 CI 서비스는 버전 없는 redis입니다.

3-4. CI는 어떤 고장을 먼저 발견하려고 할까요?

config/ci.rb의 로컬 검사 묶음에는 젬 감사, Importmap 감사, 시드 재생성도 있습니다. GitHub Actions의 작업 목록과 로컬 bin/ci의 단계는 완전히 같지 않습니다. 이름만 보고 “동일한 검사”로 가정하지 말고 두 파일을 비교해 보세요.

4아키텍처 심화 분석

위 도식의 Web Push 전송과 봇 웹훅 호출은 외부 서비스로 나가는 경계입니다. Redis는 대화 원본을 보관하는 주 데이터베이스가 아닙니다. config/cable.yml은 실시간 중계에 Redis를 지정하고, config/environments/production.rb는 작업 큐와 공유 캐시에도 Redis를 사용합니다. 대화 원본의 중심은 SQLite입니다.

4-1. 패턴 ① 서버 HTML을 재사용하고 임시 UI를 조정합니다

전송의 출발점은 app/javascript/controllers/composer_controller.js의 #submitMessage()입니다. 브라우저가 만든 clientMessageId로 임시 메시지를 넣고, 다음 화면 프레임을 기다린 다음 폼을 전송합니다. 기다리는 동안에도 사용자는 자신이 쓴 글을 볼 수 있습니다.

# app/controllers/messages_controller.rb — create의 핵심 발췌
set_room
@message = @room.messages.create_with_attachment!(message_params)
@message_html = render_to_string partial: "messages/message",
  formats: :html, locals: { message: @message }
@message.broadcast_create(html: @message_html)
deliver_webhooks_to_bots

# app/views/messages/create.turbo_stream.erb
<%= turbo_stream.append dom_id(@message.room, :messages), @message_html %>

같은 @message_html이 전송자의 HTTP 응답과 방의 방송에 사용됩니다. app/models/message/broadcasts.rb의 broadcast_create가 broadcast_append_to room, :messages를 호출합니다. “어느 대상을 어떻게 고칠지”와 HTML 조각을 전하는 방식은 Turbo Streams 공식 문서의 기본 모델과 같습니다.

여기서 중요한 구분은 확정 메시지의 DOM ID와 임시 메시지를 연결하는 ID입니다. app/helpers/messages_helper.rb의 message_tag는 확정 DOM ID를 dom_id(message), 즉 서버 기본 키에서 만듭니다. 사용자가 고른 client_message_id는 별도 데이터 속성으로 전달합니다.

// app/javascript/controllers/messages_controller.js의 #reconcilePendingMessage() 핵심 발췌
const clientMessageId = target.dataset.clientMessageId
if (target.dataset.messageId && clientMessageId) {
  const selector = `[data-pending-message][data-client-message-id="${CSS.escape(clientMessageId)}"]`
  this.messagesTarget.querySelectorAll(selector).forEach((pending) => {
    if (pending !== target) pending.remove()
  })
}

확정 메시지를 받으면 같은 임시 ID를 가진 임시 요소만 제거합니다. 사용자가 다른 메시지의 임시 ID를 재사용해도 실제 메시지의 서버 ID까지 바꿀 수는 없습니다. 이 의도는 test/system/message_id_spoofing_test.rb에 두 사용자 브라우저를 이용한 시나리오로 남아 있습니다. 임시 ID는 인증 수단도, 유일한 전송을 보장하는 키도 아닙니다.

4-2. 패턴 ② 권한 검사를 HTTP·검색·스트림에 반복 적용합니다

RoomScoped#set_room은 소속을 조회할 때 Current.user.memberships.find_by!(room_id: ...)를 사용합니다. 전체 Room에서 번호를 찾는 것과 달리, 현재 사용자의 소속에서 찾기 때문에 다른 방 번호를 넣는 것만으로 접근 범위를 넓힐 수 없습니다.

특히 app/channels/room_messages_channel.rb는 verified_stream_name_from_params만 믿지 않습니다. subscribable_room(user, stream_name)이 스트림 이름에서 방을 찾아 user.rooms.find_by로 확인합니다. 서명은 이름이 변조되지 않았음을 증명하지만, 그 사용자가 지금도 회원인지는 증명하지 않기 때문입니다.

Membership의 after_destroy_commit는 원격 연결을 다시 설정합니다. 재접속 뒤에는 새 회원 검사가 실행됩니다. 기본 Turbo::StreamsChannel로 우회하는 길도 RoomStreamsAreAuthorized#subscribed가 막습니다. 설정 연결은 config/initializers/turbo_streams_authorization.rb에 있습니다.

app/channels/application_cable/connection.rb의 SESSION_CHECK_INTERVAL = 1.minute도 살펴보세요. 연결 시점에만 로그인 상태를 검사하면 로그아웃 이후에도 열린 소켓이 남을 수 있습니다. 즉시 연결 종료 요청에 더해 하트비트에서 세션을 주기적으로 재확인합니다. 네트워크 지연까지 포함한 “항상 즉시 차단”을 보장한다고 읽어서는 안 됩니다.

4-3. 패턴 ③ 원본과 검색 색인을 함께 저장하고 알림은 확정 뒤에 보냅니다

db/migrate/20231215043540_create_initial_schema.rb는 fts5(body, tokenize=porter) 가상 테이블 message_search_index를 만듭니다. 메시지 기본 키와 FTS5의 rowid를 연결하고, HTML을 걷어낸 본문이나 첨부 파일 이름을 색인합니다.

# app/models/message.rb — 콜백 발췌
after_save :record_creation, if: :previously_new_record?
after_create_commit -> { room.push_later(self) }

# record_creation의 본문
create_in_index
room.unread_memberships(self)

# app/models/message/searchable.rb — 색인 쓰기의 핵심
execute_sql_with_binds \
  "insert into message_search_index(rowid, body) values (?, ?)",
  id, plain_text_body

새 메시지의 색인과 미읽음 상태는 저장 트랜잭션 안에서 바뀝니다. 색인 삽입이나 미읽음 갱신이 실패하면 메시지와 관련 행도 되돌아가도록 구성했습니다. test/models/message/creation_test.rb에는 이 실패를 일부러 발생시키고 메시지·첨부·색인·미읽음 상태가 함께 복구되는지 확인하는 코드가 있습니다.

수정·삭제는 생성과 시점이 다릅니다. Message::Searchable의 색인 수정은 after_update_commit, 제거는 after_destroy_commit에 연결되어 있습니다. 따라서 앞의 원자성 설명은 새 메시지 생성 경로에 해당하며, 모든 색인 갱신이 원본과 같은 트랜잭션이라는 뜻은 아닙니다.

반대로 Web Push 작업을 넣는 after_create_commit은 DB 확정 뒤에 실행됩니다. Rails 콜백 문서에서 after_save와 after_commit의 시점을 비교해 보세요. 외부에 알림을 보낸 뒤 DB 저장을 되돌려도 이미 보낸 알림을 회수할 수는 없습니다.

같이 성공해야 하는 데이터는 같은 트랜잭션에 묶고, 되돌릴 수 없는 외부 효과는 저장이 확정된 뒤에 시작합니다. 다만 DB 커밋과 Redis 큐 등록 사이까지 하나의 원자적 처리로 보장하는 구조는 아닙니다. 프로세스 종료나 큐 장애까지 다루려면 별도의 전달 보장 설계가 필요합니다.

검색은 search_reachable(user, query, size: 100)에서 메시지 ID가 큰 순서로 일치 결과 최대 1,000개를 먼저 살펴보고 접근 가능한 결과를 고릅니다. 비공개 방의 대량 기록 뒤에 오래된 접근 가능 결과가 가려지면, 권한을 적용한 관계로 다시 검색하는 경로가 있습니다. match_terms는 단어를 인용해 AND 같은 입력을 FTS 연산자가 아닌 검색어로 취급합니다.

4-4. 패턴 ④ 캐시를 버전·사용자·메모리 예산으로 제한합니다

app/models/response_cache.rb의 ResponseCache는 기본 작업자당 64MiB의 응답 캐시입니다. 한 항목은 최대 1.megabyte, 키는 최대 2.kilobytes로 제한합니다. 별도의 FragmentCache도 MemoryStore.new(size: 64.megabytes)를 사용합니다. 두 예산은 합쳐서 64MiB가 아닙니다.

# ResponseCache#current_version의 핵심 발췌
version = @observer.get_first_value("PRAGMA data_version")
if @version != version
  @entries.clear
  @bytes = 0
  @version = version
end
[ @database, @namespace, @version ]

여기서 @observer는 별도의 지속적인 읽기 전용 SQLite 연결입니다. 다른 연결에서 커밋하면 data_version 변화를 관찰하여 응답 항목을 지웁니다. 이 값은 전역 커밋 번호가 아니라 같은 연결에서 이전 값과 비교해야 하는 값입니다. SQLite 공식 설명과 구현의 연결 수명을 함께 읽으세요.

app/controllers/concerns/cached_responses.rb는 방 권한 확인 뒤 응답을 재사용하며, 키에는 사용자 ID, 세션 토큰, 전체 요청 경로, 호스트, 언어, 압축 방식, Turbo Frame 헤더 등이 들어갑니다. 캐시가 있다는 이유로 다른 사용자의 HTML을 돌려주거나 로그인 검사를 건너뛰면 안 됩니다.

RecordCache.fetch는 공유 Active Record 객체를 그대로 돌려주는 대신 불변 JSON 스냅샷에서 요청별 객체를 재구성합니다. 같은 시점의 버전인지 다시 검사하고, 트랜잭션 중에는 우회합니다. 또 ResponseCache#synchronize_render는 16개 고정 잠금으로 중복 렌더링을 줄여, URL마다 잠금 객체가 끝없이 늘지 않게 합니다.

5디렉토리 구조 해부

5-1. MVC에 실시간 통신과 작업 큐가 더해진 형태입니다

Controller는 요청을 받고, Model은 데이터와 규칙을 다루며, View는 표시할 HTML을 만듭니다. app/channels/는 오래 열려 있는 실시간 연결을, app/jobs/는 요청 이후 수행할 일을 맡습니다. 폴더가 따로 있다고 반드시 별도 서비스인 것은 아닙니다.

app/models/message.rb의 include Attachment, Broadcasts, Mentionee, Pagination, Searchable는 메시지 기능을 여러 파일로 나눕니다. app/models/message/searchable.rb 안의 이름은 Message::Searchable입니다. Rails의 이름 규칙과 자동 로딩을 함께 익히면 “이 상수는 어느 파일에서 왔지?”라는 질문에 답하기 쉬워집니다.

5-2. 방 종류는 같은 테이블, 다른 Ruby 클래스로 표현합니다

Room#direct_rooms_keep_their_type은 개인 대화방을 다른 종류로 바꾸지 못하게 합니다. 기존 참여자가 개인 대화에 동의했다는 사실을 방 유형 변경으로 무너뜨리지 않으려는 규칙입니다. 클래스 분류가 실제 사용자 약속과 연결되는 예입니다. 다만 find_or_create_for의 이름만 보고 동시 요청에서도 중복이 절대 없다고 추론해서는 안 됩니다.

5-3. 코드 규모를 범위와 함께 읽으세요

앞의 다섯 행은 커밋 c8f74a0의 추적 파일 중 app/·config/·db/·lib/에 있는 해당 확장자를 집계했습니다. 주석·빈 줄·생성된 스키마를 포함하며, Ruby 테스트 행은 별도로 test/**/*.rb를 셌습니다. 벤더 코드와 테스트까지 포함한 전체 추적 파일의 Ruby는 316개·16,181줄, JavaScript는 87개·11,139줄입니다.

물리적 줄 수는 난이도나 품질의 점수가 아닙니다. README의 Rails 5.5 KLOC는 백엔드와 템플릿의 실행 코드만 세고, 단순 HTML·테스트·의존성·생성 파일 등을 제외하는 기준입니다. 위 수치와 차이가 나는 것은 집계 범위와 방법이 다르기 때문입니다.

처음부터 모든 폴더를 읽기보다, 기능 하나를 골라 라우트·컨트롤러·모델·템플릿·테스트를 이어 읽는 편이 효과적입니다.

6학습 포인트 (기술별)

app/javascript/models/message_paginator.js는 IntersectionObserver로 처음·마지막 메시지가 보이는지 감지합니다. MAX_MESSAGES = 300과 MAX_MESSAGES_LEEWAY = 20을 두고, 초과량이 여유치보다 커지면 새로 불러온 쪽의 반대편 요소를 정리합니다. 최신 메시지를 추가하면 위쪽을, 이전 페이지를 추가하면 아래쪽을 줄입니다. 서버 페이지 크기 Message::Pagination::PAGE_SIZE = 40과 브라우저 보관 한도는 다른 설정입니다.

현재 토크나이저는 porter입니다. SQLite FTS5 문서에 따르면 Porter 처리는 영어 어간 추출을 위한 것입니다. 한국어 형태소 검색이나 임의 부분 문자열 검색이 자동으로 제공된다고 기대하면 안 됩니다. 실제 한국어 검색 품질은 조사·띄어쓰기·부분 일치 사례를 모아 따로 평가할 주제입니다.

알림 대상 선택은 Room::MessagePusher#relevant_subscriptions에 있습니다. 비활성 사용자를 제외하고, 자기 메시지를 제외하며, 연결 상태와 알림 설정을 반영합니다. 외부 전송 코드를 읽기 전에 누가 알림을 받아야 하는지부터 표로 만드는 연습이 좋습니다.

기술 이름을 나열하는 대신, 각 기술이 책임지는 상태와 실패했을 때 남는 상태를 설명해 보세요.

6-6. 보안 코드는 “누가 입력을 선택하는가”로 읽습니다

SECURITY.md는 관리자를 서버 운영자로 보는 신뢰 모델을 명시합니다. 일반 회원이 붙인 URL의 미리보기는 RestrictedHTTP::PrivateNetworkGuard로 목적지를 검증하지만, 관리자가 설정한 봇 웹훅은 내부 주소를 허용합니다. 같은 HTTP 호출이어도 입력을 고르는 주체와 권한이 달라 정책이 다릅니다.

첨부 인증도 경계를 세밀하게 봐야 합니다. config/initializers/active_storage_authentication.rb는 직접 업로드 메타데이터 생성과 디스크 쓰기에 세션 검사를 더하지만, 모든 다운로드에 방별 회원 검사를 추가하는 코드는 아닙니다. 서명된 파일 URL을 보유한 사람의 접근과 현재 방 소속의 의미를 구분하세요.

7하드웨어 / 시스템 요구사항

7-1. 소스와 운영 문서가 요구하는 환경

브라우저 숫자는 코드가 선언한 접근 기준이며, 모든 기능을 해당 버전에서 각각 검증했다는 뜻은 아닙니다. 개발 준비 스크립트에는 Homebrew·pacman·apt 분기가 있지만, 이를 근거로 모든 OS에서 동일한 설치가 보장된다고 해석해서는 안 됩니다.

개발 가이드는 bin/setup을 통합 준비 절차로 안내하지만, 실제 apt 분기는 libsqlite3-0와 ffmpeg를 설치하고 mise가 없으면 중단합니다. 또한 Docker·CI의 시스템 패키지 목록에는 libvips가 있지만 이 준비 스크립트의 패키지 목록에는 없습니다. 안내의 큰 흐름과 OS별 사전 준비 범위를 구분해서 읽으세요.

7-2. 프로세스 수가 메모리 예산을 바꿉니다

config/puma.rb는 웹 작업자 수의 기본을 (Concurrent.processor_count * 0.666).ceil로 계산합니다. 스레드는 기본 최소·최대 5개이고, 환경변수 WEB_CONCURRENCY, RAILS_MAX_THREADS, RAILS_MIN_THREADS로 조정합니다. DB 풀의 미지정 기본값은 10이므로 스레드의 기본 5와 같지 않습니다.

# 설정을 읽고 계산하는 예: 프로세스가 CPU 4개를 인식한다고 가정
웹 작업자 기본값 = ceil(4 × 0.666) = 3
웹 스레드 수     = 작업자마다 기본 5
작업 큐 작업자   = ceil(4 × 0.5) = 2

# 응답 캐시와 조각 캐시의 설정 예산만 계산하는 별도 예
웹 작업자 2개 × (응답 64 MiB + 조각 64 MiB) = 256 MiB
# Ruby 객체·DB 연결·Redis·작업 큐·미디어 변환 메모리는 별도다.

이는 설정식의 계산 예이며 실제 RAM 사용량 측정치가 아닙니다. JOB_CONCURRENCY 환경변수 설정도 Puma 파일에 있지만, config/resque-pool.yml의 기본 작업자 수 식은 별도로 확인해야 합니다. 이름이 비슷하다고 같은 설정이 자동 적용된다고 가정하지 마세요.

필요한 RAM은 사용자 수 하나로 정해지지 않고, 프로세스 수·캐시 예산·첨부 처리의 최대 작업량을 합쳐 판단해야 합니다. 응답 캐시만 끄는 CAMPFIRE_RESPONSE_CACHE_MB=0은 조각 캐시의 고정 64MiB 예산까지 없애는 설정이 아닙니다.

7-3. 첨부 파일이 디스크와 순간 메모리를 좌우합니다

Message::Attachment의 썸네일 크기는 최대 1200 × 800입니다. 미리보기 대상의 픽셀 상한은 250_000_000이며, 이 숫자는 업로드 파일의 바이트 제한이 아닙니다. 해상도를 읽지 못하거나 상한을 넘는 이미지·영상에는 미리보기를 만들지 않습니다. 작은 압축 파일도 해제하면 큰 메모리를 사용할 수 있습니다.

저장 공간을 계획할 때는 대화 DB + 원본 첨부 + 미리보기 + WAL + 백업 스냅샷 + 여유 공간을 보세요. lib/rails_ext/time_limited_video_previewer.rb에는 외부 미리보기 명령의 TIME_LIMIT = 10초가 있습니다. 이 제한이 전체 요청의 메모리나 모든 이미지 처리 시간을 제한하는 것은 아닙니다.

7-4. 백업과 복구도 시스템 요구사항입니다

script/admin/prepare-backup의 Backup.create는 SQLite3::Backup API로 일관된 DB 스냅샷을 storage/backups/에 만듭니다. hooks/pre-backup은 이 스크립트를 호출하고, hooks/post-restore는 스냅샷을 복원한 뒤 기존 -wal·-shm 파일을 제거합니다.

실행 중인 SQLite 파일 하나만 복사하는 방식은 운영 가이드의 절차와 다릅니다. 스냅샷과 첨부를 함께 보존하고, 별도 머신에도 백업을 둘 공간을 계획하세요. 컨테이너를 지워도 데이터가 남는 성질은 Docker 볼륨 문서에서 더 배울 수 있습니다.

8직접 해볼 수 있는 실습 과제

앞의 설명을 따라 읽는 데 서버 실행은 필요하지 않습니다. 아래 1번은 소스 읽기만으로 완성할 수 있습니다. 실행·변경이 필요한 나머지 과제는 개인 실습 환경과 별도 데이터로 진행하세요. 각 과제의 결과물은 “동작했다” 한마디보다 전후 상태와 실패 사례를 포함하는 편이 좋습니다.

8-1. 실행 환경을 준비할 때 먼저 읽을 명령

# docs/development.md의 개발 흐름 — 개인 실습 사본에서 검토할 명령
bin/setup
bin/dev

# 모델·요청·채널 테스트와 브라우저 시스템 테스트
bin/rails test
bin/rails test:system

bin/setup은 단순히 폴더 안의 파일만 준비하는 명령이 아닙니다. 패키지 설치, Ruby 설치, 젬 설치, DB 준비, Redis 컨테이너 시작과 검사 도구 설치를 수행합니다. 실행 전에 파일을 읽고 자신의 실습 환경에서 필요한 변경 범위를 확인하세요. --reset은 DB·첨부 초기화 경로가 있으므로 기본 학습 순서에서 필요하지 않습니다.

9관련 기술 심화 학습 로드맵

주당 3~5시간을 가정한 학습 계획입니다. 이미 아는 문법은 빠르게 지나가되, 각 주의 결과물을 남기세요. 처음부터 캐시나 Web Push 연결 풀을 모두 이해하려고 하기보다 요청과 데이터 관계를 먼저 익히는 편이 좋습니다.

9-1. 중간 점검: 설명이 막히는 지점을 다음 학습 주제로 삼으세요

• 1~2주차: Room.find(id)와 Current.user.rooms.find(id)의 차이를 설명할 수 있나요?
• 3~4주차: 임시 메시지를 없애는 기준과 DB 색인을 되돌리는 기준을 구분할 수 있나요?
• 5~6주차: 세션 종료·방 탈퇴·컨테이너 재시작 때 각각 어떤 상태가 사라지는지 설명할 수 있나요?

학습의 끝은 모든 파일을 읽는 것이 아니라, 기능을 바꿀 때 영향을 받을 데이터·화면·권한·작업을 스스로 찾을 수 있는 상태입니다.

9-2. 더 깊이 읽을 두 갈래

성능에 관심이 있다면 lib/rails_ext/sqlite_wal_checkpoint.rb를 읽으세요. 기본 간격 0.25초, 실패 시 최대 30.0초까지의 대기 증가, 파일 잠금을 통한 실행 주체 선택, PRAGMA wal_checkpoint(PASSIVE)가 연결됩니다. config/database.yml의 wal_autocheckpoint: 0과 Puma의 포크 전후 훅까지 함께 봐야 완성됩니다.

브라우저 보안에 관심이 있다면 InlineScriptHashes#script_sources를 읽으세요. 커밋 c8f74a0은 Importmap과 호스트에 따라 정해지는 스크립트 허용 목록을 재사용합니다. 캐시 키에는 Importmap JSON, 기본 URL, 호스트·포트, 상대 경로 루트가 들어가고 마지막 결과 하나만 보관합니다. 성능을 높이면서 임의 호스트 입력으로 캐시가 끝없이 커지지 않게 한 선택입니다.

10핵심 키워드 사전

용어를 다시 읽을 때는 “이 기술이 없다면 어느 기능을 내가 직접 만들어야 할까?”라고 물어보세요. 예를 들어 Turbo Streams를 빼면 화면 갱신 규약을, FTS5를 빼면 검색 구조를, 작업 큐를 빼면 요청과 느린 외부 호출의 관계를 다시 설계해야 합니다.

11참고 링크

11-1. 공식 저장소와 운영 문서

• basecamp/once-campfire 공식 저장소 — 코드, 이슈, 릴리스의 출발점입니다.
• README · c8f74a0 — 기능, 이미지 배포, 다른 구현과의 성능 표를 확인합니다.
• 개발 가이드 · c8f74a0 — 준비 명령, 개발 서버, 푸시 키, 테스트 흐름입니다.
• 자체 호스팅 가이드 · c8f74a0 — 볼륨, 비밀값, TLS, 업그레이드, 백업·복구를 읽습니다.
• 보안 신뢰 모델 · c8f74a0 — 관리자 설정과 일반 회원 입력을 구분하는 근거입니다.
• 릴리스 v1.5.6 — 분석일의 최신 릴리스 항목입니다.

11-2. 소스 코드로 돌아가는 바로가기

11-3. 관련 기술의 공식 학습 문서

• Rails: Active Record 콜백 — 저장 생명주기와 트랜잭션 콜백을 비교합니다.
• Turbo: Streams — HTML 조각과 대상 ID로 화면을 고치는 규약입니다.
• Stimulus: 소개 — HTML에 작은 동작을 연결하는 관점을 익힙니다.
• SQLite: FTS5 — 가상 테이블, MATCH, 토크나이저의 의미를 확인합니다.
• SQLite: PRAGMA data_version — 관찰 연결과 값 비교의 범위를 확인합니다.
• Docker: 볼륨 — 데이터가 컨테이너의 수명과 분리되는 이유를 배웁니다.
• Slack 공식 소개 — 비교 표의 채널·연동 설명에 대한 원문입니다.
• GitHub Trending Ruby Monthly — 순위는 계속 바뀌므로 분석일과 함께 읽으세요.

현재 상태 (2026-10-23 확인)

저장소 생성일은 제품이 처음 만들어진 날짜와 같다는 뜻이 아닙니다. 예를 들어 마이그레이션 파일에는 2023~2024년의 날짜도 있습니다. GitHub 저장소 메타데이터와 소스 안의 개발 흔적은 서로 다른 정보를 나타냅니다.