저는 유지 관리자 중 한 명이라서, 이 글은 일종의 자기 홍보입니다. 저는 좋아요 수보다 솔직한 피드백을 원합니다.
SurfSense가 무엇인지 설명드리자면, 이것은 오픈 소스(Apache-2.0) NotebookLM 대안 프로그램입니다. 문서에서 인용 기반 Q&A, 마인드맵, 플래시카드, 퀴즈 및 팟캐스트를 제공하며, Word, PDF, PowerPoint, Excel 파일을 작성하고 사용자의 자체 파일을 새로운 사본으로 편집하는 에이전트 기능을 갖추고 있습니다. 특히 Word 파일의 경우 추적 변경(tracked changes) 형태로 되돌려 받습니다.
처음에는 데스크톱 앱으로 시작했지만, 버전 2.3.0부터는 동일한 앱을 하나의 컨테이너로 실행할 수 있게 되었습니다. 왜 자체 호스팅해야 할까요? NotebookLM은 모든 문서를 Google에 전송하며 Gemini와만 작동합니다. 이 때문에 계약서, 고객 파일, 의료 기록 또는 회사 문서에는 사용할 수 없습니다. SurfSense는 사용자의 서버에 문서를 보관하고 어떤 모델과도 함께 작동할 수 있습니다.
이 컨테이너는 ghcr.io/modsetter/surfsense 이미지 하나로 구성되어 있으며, 하나의 서비스와 하나의 /data 볼륨만 필요합니다. 별도로 Postgres나 Redis 같은 다른 서비스를 실행할 필요가 없습니다. Caddy만이 리스닝하는 유일한 요소입니다. 나머지 모든 것은 컨테이너의 루프백(loopback) 내부에 머무르며 Docker 소켓이 필요하지 않습니다.
로컬 모델은 CPU에서 구동됩니다 (llama.cpp, 로컬 OCR, 임베딩 및 음성 기능 포함). 또는 Ollama, vLLM 또는 네트워크상의 모든 OpenAI 호환 API를 지정할 수 있습니다. 계정 없이 비밀번호 하나만 사용합니다. 첫 방문 시 또는 SURFSENSE_PASSWORD 환경 변수를 통해 비밀번호를 설정할 수 있으며, 자체 리버스 프록시가 처리하는 경우 로그인 기능을 끌 수도 있습니다. LAN을 통한 Caddy의 자체 인증 기관(CA)을 이용하거나 공개 도메인의 경우 Let's Encrypt를 사용하여 HTTPS를 적용할 수 있습니다.
실행 방법은 다음과 같습니다:
curl -fsSL https://raw.githubusercontent.com/MODSetter/SurfSense/main/docker/scripts/install.sh | bash
또는 리포지토리에서 docker/surfsense/docker-compose.yml과 .env.example 파일을 가져와서 docker compose up -d를 실행할 수 있습니다.
이 프로그램은 포트 4929와 HTTPS용 포트 4943에서 작동합니다. 스크립트를 다시 실행하면 업데이트됩니다. 현재는 amd64 및 CPU 전용으로 사용 가능하다는 점을 알려드립니다. GPU 이미지와 arm64 버전도 계획 중입니다. 이 이미지는 Docling, torch 및 약 1GB의 번들 모델이 포함되어 여러 GB에 달합니다. 채팅 모델은 실행 시간에 /data 디렉터리에 다운로드됩니다.
Docker가 공개한 포트는 ufw를 우회하므로, 서버가 인터넷에서 접근 가능하다면 첫 시작 전에 SURFSENSE_PASSWORD를 설정해야 합니다.
개발 과정에서 AI를 활용한 방법
코드의 대부분은 AI 코딩 어시스턴트(AI coding assistants)를 사용하여 작성되었으며, 주로 Claude Code와 일부 Cursor를 사용했습니다. 유지 관리자들은 기능을 설계하고, 모든 변경 사항을 검토하며, 릴리스를 테스트합니다. 새로운 동작은 실패하는 테스트(failing test)로 시작하며, 각 기능에는 어시스턴트가 변경하기 전에 읽는 아키텍처 문서(architecture doc)가 있습니다.
레포지토리(Repo): https://github.com/MODSetter/SurfSense
문서(Docs): https://surfsense.com/docs
제출자: /u/FurtiveMirth [링크] [댓글]