이미 소유한 전자책을 직접 운영하는 서버에 올려두고 웹에서 보고 싶다는 요구는 오래됐지만, 대개는 별도의 데이터베이스와 관리 콘솔을 갖춘 무거운 미디어 서버로 귀결되곤 했다. 오픈소스 프로젝트 'Bookshelf'는 그 반대 방향을 택한다. 데이터베이스를 아예 두지 않고, 파일과 오브젝트 스토리지만으로 전자책 서재를 구성한다. 서버 렌더링된 한 장의 페이지가 책 목록을 보여주고, 검색 상자로 걸러내며, 다운로드를 제공하고, 브라우저 안에서 EPUB과 PDF를 각각의 전용 리더로 읽게 해준다. 구조를 단순하게 유지한 대신, 어디에 데이터를 둘지에 대한 선택지를 명확히 나눠 제시하는 것이 특징이다.
두 가지 배치 방식
Bookshelf는 같은 애플리케이션을 두 경로로 배포할 수 있다. 하나는 Cloudflare Worker가 R2 버킷 위에서 도는 방식이고, 다른 하나는 Node 서버가 디스크의 특정 디렉터리 위에서 도는 방식이다. 전자는 컨테이너가 필요 없이 Cloudflare 계정과 wrangler 로그인만으로 동작하며, 프로젝트에는 버킷 이름과 Worker 이름을 담은 파일 두 개가 들어 있어 직접 수정하도록 되어 있다. 이 두 설정은 어느 버킷이 서재를 담는지에 대해 서로 일치해야 하며, 업로드 전에 상호 검증을 거쳐 불일치가 있으면 그대로 올리지 않고 오류로 보고한다. 값이 어긋난 채 배포돼 빈 서재만 뜨는 흔한 실수를 사전에 막으려는 설계다.
후자인 파일시스템 방식은 Node 서버로 동작하며 Docker 이미지도 이 쪽을 겨냥해 만들어졌다. 이미지는 비루트 사용자로 실행되고, 그 사용자가 소유한 /data 디렉터리를 만들어 네임드 볼륨이 애플리케이션이 쓸 수 있는 소유권을 물려받게 한다. 호스트 디렉터리를 바인드 마운트하려면 먼저 chown이 필요하다. 실제로 백업해야 할 대상은 'library'라는 네임드 볼륨 하나로 압축되는데, 여기에는 발행된 책뿐 아니라 프로필과 읽던 위치까지 애플리케이션이 기록하는 모든 것이 담긴다.
표지 생성과 실행 환경
동작 환경에는 제약이 있다. Node 24 이상과 유닉스 계열 시스템이 필요하고, 동기화 도구가 which로 이미지 처리 도구를 찾기 때문에 윈도우는 지원하지 않는다. 표지 이미지는 cwebp와 pdftoppm이 설치돼 있을 때 더 나은 품질로 뽑히며, 이 둘을 함께 담은 Docker 이미지를 쓰면 호스트에 아무것도 설치하지 않고도 표지가 제대로 만들어진다. 책이 아직 없다면 npm run demo로 저작권이 만료된 공개 도서 아홉 편(EPUB 여덟, PDF 하나)을 생성해 화면 구성을 그대로 재현해볼 수 있다. 제목과 저자는 실재하는 고전이지만 내부 본문은 자리 채움용 텍스트라는 점은 알아둘 만하다.
쓰기 차단과 인증 부재
실무자가 가장 주의해야 할 부분은 보안 모델이다. Bookshelf에는 인증이 전혀 없다. 앱에 접근할 수 있는 사람은 누구나 전체 서재를 읽고 내려받을 수 있으므로, 신뢰할 수 있는 네트워크 안에 두거나 호출자를 확인하는 무언가 뒤에 배치해야 한다. 프로젝트가 제공하는 안전장치는 인증이 아니라 읽기 전용 모드다. 외부에 노출되는 배치에서는 스토리지가 계속 서빙은 하되 쓰기를 받지 않도록 전환된다. 프로필은 추가·이름 변경·삭제가 막히고, 읽던 위치는 다시 브라우저에 저장되는 방식으로 되돌아간다. 이는 쓰기가 불가능한 스토리지 제공자를 만났을 때와 동일한 동작으로, 앱 입장에서는 같은 상황으로 취급된다. 이미 존재하는 프로필 사이를 오가는 것은 쿠키일 뿐 변경이 아니므로 그대로 동작한다.
이 제약이 폼을 숨기는 방식이 아니라 실제로 쓰기가 일어나는 지점에서 강제된다는 점은 눈여겨볼 만하다. 즉 폼을 우회해 액션을 직접 POST해도 동일하게 거부된다. UI를 감추는 수준의 방어가 실제로는 얼마나 쉽게 뚫리는지를 감안하면, 서버 계층에서 차단을 보장하는 설계는 셀프호스팅 도구로서 신뢰도를 높이는 선택이다. 다만 어디까지나 '쓰기'만을 막을 뿐, 열람과 다운로드 자체를 통제하는 접근 제어는 여전히 운영자의 몫으로 남는다.
확장성과 한계
구조적으로 흥미로운 지점은 스토리지 제공자가 확장 포인트로 열려 있다는 것이다. 제공자는 반드시 이 저장소 안에 있을 필요가 없고, 제3자가 패키지로 배포한 것을 설치해 설정에서 이름으로 지정할 수 있다. R2와 로컬 디렉터리 외의 백엔드를 붙이고 싶은 조직이라면 이 확장 지점이 실질적인 선택지가 된다. 빌드는 Turborepo가 의존 관계를 먼저 처리하는 방식으로 구성되며, 테스트는 패키지와 앱의 서비스 계층까지는 닿지만 페이지 자체는 다루지 않으므로, 기여할 때는 무엇을 실행했는지 함께 밝혀 달라는 안내가 붙어 있다.
정리하면 Bookshelf는 '내가 이미 가진 전자책'을 최소한의 인프라로 웹에서 다루려는 사람에게 맞춰진 도구다. 데이터베이스가 없다는 점은 백업과 운영 부담을 크게 줄여주지만, 그 대가로 다중 사용자 권한 관리나 세밀한 접근 제어 같은 기능은 애초에 범위 밖이다. 저작권 역시 도구가 책임지지 않으며, 서재에 올린 책의 권리 문제는 이용자와 출판사 사이의 일로 명시돼 있다. 개인이나 소규모 팀이 신뢰할 수 있는 망 안에서 가볍게 굴릴 서재로는 합리적인 선택이지만, 인증을 리버스 프록시 등으로 별도 마련해야 한다는 전제를 잊지 않는 것이 실무적으로 중요하다.