LeafWiki Docker Compose 설치: 단일 바이너리 셀프 호스팅 위키 띄우기

Wiki.js나 Outline을 홈랩 문서용으로 올리려다 DB·런타임 의존성이 부담되는 경우가 있습니다. LeafWiki는 단일 Go 바이너리와 디스크 Markdown으로 동작하는 셀프 호스팅 위키입니다.

직접 돌려보지는 않았습니다. 공식 README와 v0.11.4 릴리스 기준으로 정리했습니다. 저라면 런북·홈랩 문서만 가볍게 남길 때 Postgres 묶음보다 LeafWiki Docker Compose를 먼저 보겠습니다.

1. 맞는 경우

• 런북, 홈랩 문서, 팀 노트를 폴더 트리로 관리하려는 경우입니다.
• 페이지를 일반 .md 파일로 남기고 cp -r 백업을 원하는 경우입니다.
• Linux, macOS, Windows, Raspberry Pi 중 한 곳에 가벼운 위키만 올릴 경우입니다.

Confluence급 승인 흐름이나 실시간 공동 편집이 필요하면 맞지 않습니다. 공식 문서도 그 범위를 좁혀 둡니다. Docker 서비스 운영 자체는 n8n Docker Compose 설치 글과 비슷한 감각으로 보시면 됩니다.

2. Docker Compose 설정

Compose 파일이 있으면 이미지 한 개와 데이터 볼륨만 준비하시면 됩니다. 공식 예시는 아래 형태입니다. yourSecret, yourPassword는 반드시 바꿔 쓰셔야 합니다.

services:
  leafwiki:
    image: ghcr.io/perber/leafwiki:latest
    container_name: leafwiki
    user: 1000:1000
    ports:
      - "8080:8080"
    environment:
      - LEAFWIKI_JWT_SECRET=yourSecret
      - LEAFWIKI_ADMIN_PASSWORD=yourPassword
      - LEAFWIKI_ALLOW_INSECURE=true
    volumes:
      - ${HOME}/leafwiki-data:/app/data
    restart: unless-stopped

한 줄 실행도 됩니다.

docker run -p 8080:8080 \
  -v ~/leafwiki-data:/app/data \
  ghcr.io/perber/leafwiki:latest \
  --jwt-secret=yoursecret \
  --admin-password=yourpassword \
  --allow-insecure=true

--allow-insecure=true는 plain HTTP 로그인 쿠키용입니다. HTTPS 리버스 프록시 뒤에서는 빼고 X-Forwarded-Proto: https를 넘기면 됩니다. 데이터 디렉터리는 컨테이너 사용자(1000:1000)가 쓸 수 있어야 합니다.

3. 실행 모드

기본은 로그인 필수 사설 위키입니다. 공개 문서는 --public-access=true로 읽기만 열고, 편집은 로그인 사용자만 허용합니다. 로컬 노트용 --disable-auth도 있습니다.

인증을 끈 LeafWiki는 공인망에 올리면 안 됩니다. 공식 README도 --disable-auth를 신뢰 가능한 내부망·로컬에서만 쓰라고 권합니다. 역할은 admin, editor, viewer 세 가지입니다. CSRF 보호와 인증 엔드포인트 레이트 리미팅은 v0.7.0부터 기본입니다.

페이지 내용은 디스크 Markdown이고, 링크·태그·검색 인덱스는 옆의 경량 SQLite에 둡니다. 리비전 히스토리와 페이지 이동 시 링크 자동 갱신은 feature flag로 켭니다.

확인

브라우저에서 http://localhost:8080을 열고 관리자 계정으로 로그인하시면 됩니다. 트리 탐색과 페이지 저장이 보이면 설치는 끝난 상태입니다. 백업은 앱을 잠시 멈춘 뒤 ~/leafwiki-data를 복사하시면 됩니다.