SilverBullet — 설치·사용 가이드 (공식 문서 한글 정리)

11. 한눈에 보기

▸ 무엇인가
README의 정의: 프로그래머블(코드로 동작을 바꿀 수 있는)·프라이빗·브라우저 기반·오픈소스·셀프호스팅(내 컴퓨터나 서버에 직접 설치하는) 개인 지식 데이터베이스. README는 '스테로이드 맞은 메모 앱(notes app on steroids)'이라고도 부릅니다.
▸ 구성(README)
· 라이브 미리보기 편집기(쓰는 즉시 서식이 보이는 화면)
· 위키식 링크
· 내장 데이터베이스와 쿼리 언어(메모를 조회하는 명령)
· Space Lua 스크립트 환경(Lua 언어를 SilverBullet용으로 만든 방언)
▸ 저장 방식: 마크다운(간단한 기호로 서식을 다는 글 형식) 페이지 모음으로 보관하며, 이 모음을 Space(스페이스)라고 부릅니다. 파일은 내가 관리하는 디스크의 평범한 폴더에 있습니다.
▸ 만든 곳: GitHub silverbulletmd/silverbullet. LICENSE.md 표기는 Copyright 2022, Zef Hemel.
▸ 라이선스: MIT(Server와 sb CLI).
▸ 비용: Server는 'Open source and free'. Desktop 앱은 개인·교육용 무료, 업무용은 Pro 라이선스 필요.
▸ 어디서 돌아가나: 서버를 내 기기에서 실행하고 브라우저(휴대폰 포함)로 접속합니다. 데스크톱 앱은 macOS·Windows·Linux용이 있고, 호스팅 업체에 운영을 맡기는 방법도 원문에 안내돼 있습니다.

22. 이런 분께 맞아요 / 이럴 땐 맞지 않아요

▸ 이런 분께 맞아요
· 글 쓰는 유형: 라이브 미리보기 마크다운 편집기.
· 아웃라이너 유형(글머리표로 생각을 정리하는 분): 아웃라인 도구.
· 할 일 관리: Tasks 기능.
· 데이터베이스 유형: 객체(Objects)와 쿼리(SLIQ).
· 코딩을 조금 하는 분: Space Lua로 내용 자동 생성, 나만의 명령·페이지 템플릿·위젯 만들기.
· 공식 사이트의 네 가지 쓰임새: 개인 지식, 팀 위키, 코드와 함께 두는 문서, 가족 공용 공간.
· 내 파일을 계속 갖고 싶은 분: 다른 편집기로 열고, git에 넣고, 원하는 대로 백업할 수 있다고 원문에 적혀 있습니다.
▸ 맞지 않을 수 있어요
· 서버를 Windows·macOS 기본 파일 시스템에서 실사용하려는 경우: 원문은 강하게 권하지 않고 Linux를 권장합니다.
· 회사 업무에 데스크톱 앱을 무료로 쓰려는 경우: Pro 라이선스가 필요합니다.
· 편집은 허용하되 스크립트는 막고 싶은 경우: 한 스페이스 안에 그런 중간 권한은 없다고 원문이 밝힙니다.

33. 시작 전에 준비할 것

▸ 서버 기기: 터미널(명령 창)을 쓸 수 있는 인텔 호환 64비트 또는 ARM 64비트 기기. 수백 MB RAM이면 충분하고 라즈베리 파이도 됩니다.
▸ 서버 바이너리(실행 파일 하나) 지원: macOS(Intel, Apple Silicon), Linux(x86_64, arm64 — 라즈베리 파이는 64비트 배포판 필요), Windows(64-bit), FreeBSD(x86_64).
▸ 도커 이미지 지원: 64-bit Intel, 64-bit ARM, 32-bit ARM(ARMv7).
▸ 파일 시스템
· Linux 권장.
· macOS 기본 APFS는 대소문자를 구분하지 않습니다. 맥에서 돌리려면 대소문자 구분을 켠 새 APFS 볼륨을 쓰라고 안내합니다.
· Windows NTFS도 기본은 대소문자 비구분이라 Windows 배포는 권장하지 않습니다.
· 이 제한은 서버가 도는 곳에만 해당하고, 접속하는 브라우저 기기와는 무관합니다.
▸ 필요한 프로그램: 도커 방식은 Docker(Compose 권장). 바이너리 방식의 추가 요구는 원문에서 확인되지 않았습니다. 소스 빌드 때만 Node.js 24+ / npm 10+와 Rust가 필요합니다.
▸ 계정·API 키: 첫 실행 때 서버 안에서 관리자 계정을 만듭니다. 외부 API 키가 필요하다는 안내는 원문에서 확인되지 않았습니다. 데스크톱 업무용은 Pro 라이선스 키가 필요합니다.
▸ 휴대폰 등 다른 기기에서 쓰려면 TLS(https 암호화 연결)를 서버 앞에 두는 것이 원문 권장입니다.

44. 설치 방법

원문은 먼저 내 컴퓨터(localhost)에서 시험하고, 마음에 들면 서버에 배포하라고 합니다. 서버 배포 순서: 1) 설치 2) 앞단에 TLS 배치 3) Getting Started로 기본 익히기.

▸ 방법 A — 서버 바이너리
1) 릴리스 페이지(https://github.com/silverbulletmd/silverbullet/releases)에서 silverbullet-server-<os>-<arch>.zip 을 받습니다(sb-<os>-<arch>.zip 은 선택용 CLI 도구).
2) 압축을 풀면 silverbullet 실행 파일 하나가 나옵니다.
3) 데이터 폴더를 만들고 지정해 실행합니다.
mkdir data
./silverbullet data
4) 포트 변경은 -p, 다른 주소(예: 같은 공유기 안 다른 기기)로 열기는 -L.
./silverbullet -p 3001 sb-data
./silverbullet -L 0.0.0.0 sb-data
5) 업그레이드(안정판 / main 브랜치를 따르는 edge판)
./silverbullet upgrade
./silverbullet upgrade-edge

▸ 방법 B — Docker Compose(원문 권장 관리 방식)
1) compose.yml 을 만듭니다. 같은 위치의 ./data 폴더(없으면 자동 생성)에 데이터가 저장됩니다.
services:
silverbullet:
image: ghcr.io/silverbulletmd/silverbullet:latest
restart: unless-stopped
volumes:
- ./data:/data
ports:
- 3000:3000
2) 실행과 로그 보기
docker compose up -d
docker compose logs -f
3) 업그레이드
docker compose pull
docker compose stop
docker compose up -d
· :latest 는 최신 정식판, :edge 는 main 최신 빌드. 기본 이미지는 Chromium 포함, 작은 이미지는 -slim 태그(:latest-slim 등).

▸ 방법 C — Compose 없이 도커로
mkdir -p data
docker run -d --restart unless-stopped \
--name silverbullet \
-p 3000:3000 \
-v ./data:/data \
ghcr.io/silverbulletmd/silverbullet:latest

▸ 방법 D — 데스크톱 앱
다운로드 페이지(https://silverbullet.md/desktop/download)에서 받습니다. macOS는 디스크 이미지, Windows는 설치 프로그램, Linux는 AppImage 또는 Flatpak. 앱은 스스로 업데이트합니다.

55. 처음 실행해 보기

1) 브라우저에서 http://localhost:3000 을 엽니다.
2) 데이터 폴더가 비어 있으면 설정 모드가 켜집니다. 첫 관리자 계정 만들기 → 첫 스페이스 만들기 순서입니다. 마크다운 페이지가 이미 있는 폴더를 지정하면 바로 하나의 스페이스로 열립니다.
3) 데스크톱 앱은 대시보드에서 New space(내 폴더로 새 스페이스) 또는 Join Space(서버 스페이스와 연결)를 고릅니다.
4) 인덱스 페이지에 최근 빠른 메모·최근 일기·안 끝난 할 일·최근 고친 페이지 네 구역이 보입니다.
5) 빠른 메모: Create quick note 버튼, 또는
Ctrl-q Ctrl-q
Inbox/ 뒤에 날짜·시간이 붙은 페이지가 열립니다. 저장 버튼은 없고 1~2초마다 자동 저장됩니다. 제목을 눌러 이름을 바꿀 수 있습니다.
6) 명령 창: 맥은 Cmd-/, 그 밖은 Ctrl-/.
7) 일기: Today's entry 버튼, Journal: Today 명령, 또는 Ctrl-q j.
8) 링크: [[Allan]] 처럼 [[page]] 형식으로 씁니다. 링크는 양방향이라, 링크된 페이지에서 어디서 언급됐는지 Linked Mention 구역에 보입니다.
9) 할 일: 아래처럼 쓰거나, 문장 뒤에 공백과 /task 를 치고 Enter.
* [ ] My task
10) 버전 확인: Client: Version 명령.

66. 알아 둘 기능

▸ 편집과 탐색
· Page Picker(페이지 고르기 창)로 이동하거나 위키처럼 링크로 이동.
· 백링크: 그 페이지를 언급한 곳이 모두 표시됩니다.
· 객체 그래프: 페이지 관계를 그림으로 보여 줍니다.
· 아웃라인, 할 일, 일기, 빠른 메모.
▸ 데이터베이스처럼 조회: 태그한 책 목록, 모든 프로젝트의 열린 할 일 등을 쿼리로 뽑습니다. 쿼리는 페이지 안에 쓰는 몇 줄의 Space Lua입니다.
▸ Lua로 확장(Space Lua)
· 공식 Lua나 LuaJIT가 아닌 자체 구현이라 약간의 차이(Quirks)가 있습니다.
· space-lua 코드 블록의 정의는 스페이스 전체에서 쓸 수 있습니다. 원문 예시:
```space-lua
--- Adds two numbers.
---@param a number First number.
---@param b number Second number.
---@return number sum
function adder(a, b)
return a + b
end
```
· 본문에 ${expression} 을 쓰면 계산 결과가 보입니다. 원문 예시: 10 + 2 = ${adder(10, 2)}
· 공식 문서 예시는 lua 로 표시돼 있으니 내 스페이스에서는 space-lua 로 바꿔 씁니다.
· 고친 스크립트 다시 불러오기: System: Reload (Ctrl-Alt-r).
· 불러오는 순서는 -- priority: <number> 주석으로 정하며 숫자가 클수록 먼저입니다.
▸ 파일과 공간
· 노트는 이미지·PDF와 함께 평범한 폴더에 마크다운으로 저장됩니다.
· 서버 하나에 여러 스페이스, 스페이스마다 주소·권한(none/read/write)·설정이 따로입니다.
· 데스크톱 앱은 어떤 서버와도 동기화할 수 있습니다.

77. 막힐 때 / 주의할 점

▸ 파일 시스템: 대소문자 비구분 파일 시스템에서는 페이지 이름과 파일 이름의 대소문자가 어긋날 때 문제가 생긴다고 원문이 경고합니다. NAS나 SyncThing 같은 동기화 도구에서 저장·동기화 문제가 나면 로컬 파일 시스템으로 바꿔 확인하라고 합니다(동기화는 파일 수정 시각이 정확히 유지된다는 전제).
▸ https 없이 쓸 때
· localhost·127.0.0.1 접속은 http여도 정상입니다. 단 그 컴퓨터에서만 됩니다.
· 같은 공유기 안 http 접속(예: http://192.168.1.20:3000)은 온라인 전용입니다. 오프라인 사용이 안 되고, 로컬 데이터 암호화와 OIDC/SSO 로그인이 꺼집니다.
· http는 트래픽을 암호화하지 않아 계정 정보와 노트가 가로채일 수 있다고 원문이 경고합니다.
· https 방법(원문): 인증 프록시(Pangolin, Authelia, Authentik), Tailscale 인증서, 클라우드 서버 + Caddy. Caddy 예시(도메인·포트는 내 것으로):
silverbullet.mydomain.com {
reverse_proxy localhost:3000
}
▸ 권한: write 권한자는 다른 사람(관리자 포함)의 브라우저에서 실행될 스크립트를 쓸 수 있으니 믿는 사람에게만 주라고 합니다. 서버 명령을 실행하는 Shell(/.shell)은 기본으로 꺼져 있습니다.
▸ 업그레이드 뒤: 페이지를 천천히 두 번 새로 고쳐야 새 버전이 적용될 수 있습니다.
▸ Space Lua: Reload가 오류 없이 끝나도 정상이라는 뜻은 아닙니다. 오류는 브라우저 콘솔 로그에 나옵니다.
▸ 원문 예시의 폴더 이름: 바이너리 문서는 mkdir data 뒤 일부 예시에서 sb-data 를 씁니다. 내가 만든 데이터 폴더 이름으로 맞춰 쓰세요.

88. 라이선스와 비용

▸ 라이선스: MIT. 공식 사이트에 SilverBullet Server와 sb CLI가 MIT 라이선스라고 적혀 있습니다. LICENSE.md는 사용·복사·수정·병합·게시·배포·재허가·판매를 허락하며, 저작권 표시와 허가 문구를 사본에 포함하는 것이 조건입니다. 보증 없이 있는 그대로(AS IS) 제공됩니다.
▸ 비용
· Server: 'Open source and free'.
· Desktop: 개인·교육용 무료, 업무용은 Pro 라이선스 필요. Pro 라이선스는 사용자 한 명 소유이고 본인 기기 여러 대에 활성화할 수 있습니다(대시보드 Pro 탭에서 키 입력 후 Activate).
· Pro 요금은 이번에 확인한 원문에서 확인되지 않았습니다(공식 pricing 페이지 참고).
· 호스팅 업체 요금은 원문에서 확인되지 않았습니다.

99. 면책 및 원문 확인

이 문서는 원저자의 공식 사이트와 깃허브 문서를 한국어로 옮겨 정리한 안내입니다. 가고파는 이 소프트웨어를 개발·배포·보증하지 않으며, 설치·사용으로 생기는 결과(데이터 손실, 보안 문제, 비용, 라이선스 위반 등)에 책임지지 않습니다. 번역·요약 과정의 오류가 있을 수 있고 원문은 수시로 바뀌므로, 설치 전에 반드시 아래 원문(공식 사이트·깃허브)에서 최신 내용을 확인하세요. 제휴 링크·광고가 없습니다.

▸ SilverBullet 추가 안내
· 데스크톱 앱을 회사 업무에 쓰려면 원문상 Pro 라이선스가 필요합니다.
· 서버를 다른 기기나 인터넷에 열기 전에 원문의 TLS·인증·권한(write) 안내를 먼저 읽으세요.

원문 주소(복사해서 브라우저 주소창에 붙여넣기):
· 공식 사이트: https://silverbullet.md
· GitHub 저장소: https://github.com/silverbulletmd/silverbullet
· 공식 문서 — 설치(Install): https://docs.silverbullet.md/Install

이 자료를 보는 방법

이 안내는 인스타그램 카드·릴스에서 다 담지 못한 내용을 담은 무료 자료입니다. 로그인이나 이메일 확인 없이 바로 읽을 수 있고, 링크는 새 창에서 열립니다.

가고파 생활 가이드 시리즈

이 자료는 가고파(Natas Market)가 생활 주제별로 만들어 두는 무료 DM 자료 중 하나입니다. 인스타그램·스레드 카드뉴스에서 줄인 설명을 여기서 자세히 풀어 씁니다.

각 자료는 카드뉴스 1편과 한 세트입니다. 카드에서 “댓글에 ○○ 남겨주세요”로 안내한 경우, 그 키워드를 남기면 이 자료 링크를 받습니다.

자주 묻는 질문