Project N.O.M.A.D. 딥다이브
— 인터넷이 끊겨도 살아있는 "오프라인 지식·AI 서버"

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README 첫 문장은 이렇다: "Project N.O.M.A.D. is a self-contained, offline-first knowledge and education server." ("완전히 자급자족하는 오프라인 우선 지식·교육 서버.") GitHub 저장소 설명은 한 발 더 나가 "offline survival computer"(오프라인 생존 컴퓨터)라는 표현까지 쓴다 — 재난·정전·오지 상황을 염두에 둔 포지셔닝이다.

이름부터 의도적이다. N.O.M.A.D. = Node for Offline Media, Archives, and Data. "노드(Node)"라는 단어가 암시하듯, 이건 클라우드 서비스가 아니라 사용자가 소유한 물리적 하드웨어 위에서 도는 독립 노드다. 설치 후에는 인터넷 연결 없이도 100% 동작하며, README는 "ZERO built-in telemetry"(내장 텔레메트리 제로)를 명시적으로 못박는다.

2왜 주목받는가

트렌딩 이유 · 경쟁 제품 대비 강점 · 최근 성장(Supply Depot 등).

경쟁 제품 비교

주목도를 끌어올린 최근 성장 포인트는 다음과 같다.

① Supply Depot — "선택형 앱 카탈로그"로 확장. 초기 버전이 Kiwix·Ollama·Kolibri·ProtoMaps·CyberChef·FlatNotes 6~7종의 핵심 앱으로 시작했다면, 지금은 Stirling-PDF·FileBrowser·Calibre-Web·IT-Tools·Excalidraw·Meshtastic/MeshCore(무전)·HomeBox(재고관리)·Vaultwarden(비밀번호 관리자)·Jellyfin(미디어 서버)까지 총 11개 추가 앱이 "설치 버튼 한 번"으로 붙는다.
② RAG가 지식 라이브러리 전체로 확장. 단순 PDF 업로드형 RAG를 넘어, 설치된 ZIM 라이브러리(Wikipedia 등)를 통째로 벡터 임베딩해 AI 챗봇이 오프라인 위키피디아 지식으로 답하게 만드는 ZIMExtractionService가 추가됐다.
③ 스스로 진화하는 인프라. 자동 업데이트(코어 앱 + Supply Depot 앱 + 콘텐츠 각각 별도 파이프라인), 디스크 사용량 수집 사이드카, 컨테이너 로그 뷰어(Dozzle) 통합까지 — "설치 후 방치해도 되는" 운영 편의성이 크게 강화됐다.
④ 결정론적 테스트 가능한 자동화. 자동 업데이트 로직을 --dry-run으로 실제 업데이트 없이 시뮬레이션할 수 있어, "언제·왜 업데이트했는지/안 했는지"를 코드로 검증 가능하게 설계했다.

3기술 스택 전체 지도

AdonisJS 풀스택 백엔드 + React/Inertia 프론트엔드 + Docker 오케스트레이션 인프라.

언어 구성은 TypeScript 92.5%, Shell 6.6%, 나머지는 Dockerfile류다. 즉 프로덕트 로직은 거의 전부 TypeScript 한 언어로 통일돼 있고(백엔드도 프론트엔드도), 셸 스크립트는 설치·업데이트·사이드카 같은 인프라 자동화에 집중돼 있다.

① 백엔드 — Command Center (AdonisJS 6)

② AI · RAG · 콘텐츠 처리 파이프라인

③ 프론트엔드

④ 인프라 · 컨테이너 오케스트레이션

4아키텍처 심화 분석

Docker-of-Docker 오케스트레이션 + 파일 기반 사이드카 통신 + RAG 파이프라인.

전체 시스템 구조도

핵심 설계 패턴 1 — 파일 기반 사이드카 통신 (자기 자신을 업데이트하기)

"실행 중인 컨테이너가 자기 자신을 업데이트"하는 건 역설적이다 — 이미지를 갈아 끼우는 도중 그 프로세스 자신이 죽을 수 있기 때문이다. NOMAD의 해법은 별도의 작은 sidecar-updater 컨테이너를 옆에 세워 두고, admin과 sidecar가 공유 볼륨(nomad-update-shared)의 파일들로만 대화하게 만드는 것이다.

이 구조의 묘미는 admin이 죽어도 updater는 살아 있다는 것이다. docker compose up -d로 admin 컨테이너가 새 이미지로 재생성되는 순간에도, 그 작업을 수행하는 프로세스(sidecar)는 admin과 별개이므로 중단되지 않는다. 상태는 DB가 아니라 단순 텍스트/JSON 파일(update-status, update-log)로 주고받는데, 이는 admin의 DB 연결이 재시작 중 끊겨도 상태 추적이 흔들리지 않게 하는 실용적 선택이다.

핵심 설계 패턴 2 — 3단계 자동 업데이트 파이프라인과 안전장치

auto_update_service.ts는 코드 몇 줄이 아니라 완결된 의사결정 파이프라인이다. GitHub Releases API를 15분 캐시로 조회하고, 정규식 ^\d+\.\d+\.\d+$로 엄격한 semver 태그만 후보로 인정한다(형식이 이상한 값이 셸 스크립트의 sed 치환에 그대로 흘러들어가면 위험하기 때문 — 방어적 설계).

같은 패턴이 세 갈래로 병렬 존재한다 — auto_update_service.ts(코어 admin 이미지), app_auto_update_service.ts(Supply Depot에서 설치한 개별 앱), content_auto_update_service.ts(ZIM·지도 같은 콘텐츠 파일). 각기 업데이트 대상은 다르지만, 시간창·쿨다운·사전점검·dry-run이라는 뼈대는 공유한다 — "같은 안전장치를 여러 도메인에 재사용"하는 좋은 예시다.

핵심 설계 패턴 3 — 스토리지 마운트 자동 추적

DockerService에는 _hostStorageRoot라는 흥미로운 필드가 있다. admin 컨테이너 자신의 /app/storage 마운트가 호스트의 어느 경로에 실제로 매핑돼 있는지를 컨테이너 안에서 역으로 알아낸 뒤, Kiwix·Ollama 같은 자식 서비스의 볼륨도 같은 호스트 경로 아래로 맞춰 생성한다. 이렇게 하면 사용자가 docker-compose.yml에서 저장 위치를 바꿨을 때, 자식 컨테이너들도 자동으로 새 위치를 따라간다 — 설정을 한 곳에서만 바꾸면 되는 "단일 진실 공급원(source of truth)" 원칙이다.

핵심 설계 패턴 4 — RAG: 문서뿐 아니라 "이미 설치된 지식"까지 임베딩

두 경로가 같은 컬렉션·같은 임베딩 파이프라인을 공유한다는 점이 핵심이다. 즉 "내가 올린 PDF"와 "설치해 둔 오프라인 위키피디아"가 하나의 지식베이스로 합쳐져, AI 챗봇이 둘을 넘나들며 답을 만든다. 임베딩 프리픽스(search_document: / search_query:)를 문서용과 질의용으로 구분하는 것은 Nomic Embed Text 계열 모델의 권장 사용법을 그대로 반영한 디테일이다.

핵심 설계 패턴 5 — 상태 캐시 + 인플라이트 중복 제거

DockerService의 서비스 상태 조회(_servicesStatusCache, _servicesStatusInflight)를 보면, 같은 순간 여러 요청이 동시에 들어와도 Docker API 호출은 단 한 번만 나가도록 프라미스를 캐싱한다. UI가 여러 컴포넌트에서 동시에 "서비스 상태 다 보여줘"를 호출해도 Docker 데몬에 중복 부하를 주지 않는, 실전에서 자주 놓치는 최적화다.

5디렉토리 구조 해부

"admin/이 사실상 저장소 전체" — AdonisJS 표준 구조 위에 도메인별 서비스·잡 계층이 얹힌 형태.

세 덩어리로 나눠 읽으면 명료하다.

① 압도적 비중의 admin/. 저장소 전체 TypeScript/TSX 파일이 331개, admin/app/만 약 2만 1천 줄이다. 서비스 계층(services/)이 22개로 가장 크고, 그 아래 잡(jobs/)·모델(models/)·컨트롤러(controllers/)가 각각 명확히 역할을 나눈다 — Controller는 요청만 받고, 실제 로직은 Service에, 무거운 작업은 Job(큐)에 위임하는 전형적 계층 분리다.

② 독립적으로 빌드되는 install/sidecar-*. 이 두 폴더는 각각 자기 자신의 Dockerfile을 갖고 별도 GitHub Actions 워크플로(build-sidecar-updater.yml, build-disk-collector.yml)로 독립 이미지로 빌드된다. admin 이미지와 릴리스 주기가 분리돼 있어, 사이드카만 고쳐도 전체 admin을 재빌드할 필요가 없다.

③ 데이터가 코드로 관리되는 collections/. 다운로드 가능한 Wikipedia 언어판·카테고리·지도 목록이 JSON 파일로 저장소에 커밋돼 있다. .github/workflows/validate-collection-urls.yml이 이 URL들의 생존 여부를 CI에서 주기 검증하는 것으로 보아, "콘텐츠 카탈로그도 코드처럼 리뷰·검증한다"는 원칙이 엿보인다.

6학습 포인트 (기술별)

이 저장소에서 "무엇을 배울 수 있는가" — 개념 → 코드 위치 → 실습 아이디어.

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

관리 앱 자체는 가볍지만, "어떤 앱을 얼마나 얹느냐"가 실제 요구사항을 결정한다.

핵심 공식: GPU VRAM이 곧 돌릴 수 있는 AI 모델 크기를 결정한다. RTX 3060(12GB)이면 13B급 모델, RTX 4090(24GB)이면 70B급까지 시야에 들어온다. AI를 아예 안 쓰거나 OpenAI 호환 API로 외부 서버에 추론을 위임하면 이 요구사항 자체가 사라진다.

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

난이도별로 손을 움직여 보는 5가지.

입문 ★☆☆☆☆

sudo apt-get update && sudo apt-get install -y curl
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh \
  -o install_nomad.sh && sudo bash install_nomad.sh
# http://localhost:8080 접속 → Easy Setup 위저드부터 진행

# admin/ 디렉토리에서 실행
node ace auto-update:dry-run --scenarios
node ace auto-update:dry-run --current=1.32.0 --force-enabled

중급 ★★★☆☆

import Docker from 'dockerode'
const docker = new Docker()
const containers = await docker.listContainers({ all: true })
console.log(containers.map(c => ({ name: c.Names, status: c.Status })))

고급 ★★★★☆

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

6주 코스 — AdonisJS 기초부터 자체 사이드카 오케스트레이션까지.

10핵심 키워드 사전

이 프로젝트를 읽을 때 반복 등장하는 용어 정리.

11참고 링크

원본을 직접 확인하고 싶을 때.