셀프 호스팅 위키 추천: BookStack, Wiki.js, Outline 비교

어떤 셀프 호스팅 위키를 운영해야 하는가

셀프 호스팅 위키를 사용하면 팀의 문서를 직접 제어하는 서버의 검색 가능한 한 곳에 모을 수 있습니다. BookStack, Wiki.js, Outline 모두 이 역할을 수행합니다. 이 도구들은 첫 페이지가 로드되기 전까지 얼마나 많은 설정을 직접 구성해야 하는지, 그리고 누가 로그인할 수 있는지에 따라 차이가 있습니다.

BookStack은 설치가 가장 가볍고 구조에 대한 고유한 철학이 확고합니다. Wiki.js는 하나의 페이지 트리 내에서 가장 다양한 편집기 선택지를 제공합니다. Outline은 세 가지 도구 중 글쓰기 경험이 가장 뛰어나지만, 외부 ID 공급자(identity provider)를 연결하기 전까지는 누구도 로그인할 수 없습니다.

아래의 모든 내용은 각 프로젝트의 공식 문서와 공개된 설정 파일을 바탕으로 작성되었습니다. 이는 벤치마크가 아닌 기능 비교입니다. 세 도구 모두 빠르게 발전하고 있으므로 버전 번호와 요구 사항에는 기준 날짜를 명시했습니다.

구조가 곧 실질적인 선택입니다

BookStack은 콘텐츠의 형태를 고정합니다. 페이지는 책 안에 존재하고, 책은 챕터를 포함할 수 있으며, 서가는 책들을 그룹화합니다. 다섯 번째 계층을 임의로 만들 수는 없습니다. 이러한 제한이 곧 제품의 핵심입니다. 페이지가 들어갈 위치가 하나뿐이므로, 새로운 작성자도 페이지를 어디에 배치해야 할지 즉시 알 수 있습니다. 그 대가로 이 형태에 맞지 않는 콘텐츠는 강제로 끼워 맞춰야 합니다.

Wiki.js는 디스크의 폴더와 같은 경로 트리 방식을 사용합니다. ops/backup/restic에 있는 페이지는 사용자가 배치한 곳 어디든 위치할 수 있으며, 깊이 또한 직접 결정합니다. 두 사람이 같은 주제를 서로 다른 경로에 분류하는 것을 막을 방법이 없으므로, Wiki.js 인스턴스에는 트리 구조를 관리할 담당자가 한 명 필요합니다.

Outline은 문서 안에 문서가 중첩되는 컬렉션 방식을 사용합니다. 문서를 이동하려면 마우스로 드래그해야 합니다. 이 세 가지 도구 중 가장 유연하지만, 그만큼 관리가 소홀해지기 쉽다는 단점도 있습니다.

BookStack: 최소 설치

BookStack은 MySQL을 백엔드로 사용하는 PHP 애플리케이션이다. 2026년 10월 기준으로 문서에 명시된 요구 사항은 PHP 8.2 이상, MySQL 8.0 또는 MariaDB 10.6 이상이다. 소스에서 설치하는 경우 Composer 2.2 이상도 필요하다. 현재 릴리스 계열은 2026년 9월 24일에 릴리스된 26.09이며, 최신 안정 릴리스는 26.09.1이다. 26.09부터는 APP_KEY 값을 설정해야 하며, 아래의 컨테이너 단계에서 이미 설정한다.

프로젝트는 현재 22.04, 24.04, 26.04인 지원 Ubuntu LTS 릴리스에만 설치 스크립트를 제공한다. 24.04용 스크립트는 Apache, MySQL 8.0, PHP 8.3을 설치한다. 26.04에서는 아래 명령에서 installation-ubuntu-26.04.sh을 대신 사용한다. 이 명령은 MySQL 8.4와 PHP 8.5를 설치한다.

wget https://codeberg.org/bookstack/devops/raw/branch/main/scripts/installation-ubuntu-24.04.sh
chmod a+x installation-ubuntu-24.04.sh
sudo ./installation-ubuntu-24.04.sh

실행하기 전에 해당 스크립트의 경고를 읽어야 한다. 문서에는 이 스크립트가 "새로 설치한 OS에서만 사용해야 하며, Apache, MySQL 8.0, PHP 8.3을 설치하고 시스템에 이미 구성된 웹 설정을 덮어쓸 수 있다"고 명시되어 있다. 이미 port 80에서 응답하는 서버에서는 이 스크립트가 해당 포트를 사용하고 Apache 설정을 다시 작성한다. 이런 환경에서는 컨테이너를 사용하거나 Ubuntu 24.04의 기존 LAMP 스택 위에 BookStack을 수동으로 설치한다.

컨테이너 방식에서는 BookStack 문서가 안내하는 LinuxServer.io 이미지를 사용한다. BookStack은 세션 암호화 키가 필요하며 키가 없으면 페이지를 제공하지 않는다. 따라서 먼저 키를 생성한다.

docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

출력된 값을 APP_KEY에 복사한 다음 서비스를 작성한다.

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - APP_URL=https://wiki.example.com
      - APP_KEY=paste_the_generated_key_here
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USERNAME=bookstack
      - DB_PASSWORD=change_me
      - DB_DATABASE=bookstackapp
    volumes:
      - ./config:/config
    ports:
      - 6875:80
    restart: unless-stopped

APP_URL은 독자가 실제로 입력하는 주소와 일치해야 하며, scheme과 port를 포함해야 한다. 이를 http://localhost로 설정한 다음 사이트를 HTTPS로 제공하면 생성된 링크와 리다이렉트가 잘못된 호스트를 가리킨다. 그러면 독자는 로그인 페이지가 자기 자신으로 되돌아가는 현상을 보게 된다. compose 파일이 익숙하지 않다면 이 절차를 진행하기 전에 VPS에서 Docker Compose 기초부터 확인한다.

컨테이너가 실행 중인지뿐 아니라 애플리케이션이 응답하는지도 확인하면서 시작한다.

docker compose up -d
docker compose ps
curl -sI http://127.0.0.1:6875/login

200 OK가 나타나면 PHP 애플리케이션이 시작되어 데이터베이스에 연결된 것이다. 500은 대부분 APP_KEY가 비어 있거나 데이터베이스 자격 증명이 일치하지 않는다는 뜻이다. 기본적으로 BookStack은 오류를 컨테이너 출력이 아니라 로그 파일에 기록한다. 따라서 호스트에서 ./config/log/bookstack/laravel.log를 열어 두 원인 중 어느 쪽인지 확인한다. docker compose logs bookstack은 컨테이너 자체의 시작 메시지를 표시하며, 여기에 애플리케이션 오류가 포함되지 않을 수 있다.

Wiki.js: 하나의 트리, 여러 편집기

Wiki.js는 Node.js 애플리케이션이다. 문서에 나온 Docker 설정은 PostgreSQL과 함께 사용하지만, 이 소프트웨어는 MySQL, MariaDB, MSSQL 및 SQLite도 지원한다. 다음은 프로젝트의 자체 Docker 페이지에 있는 compose 파일이다.

services:
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: wiki
      POSTGRES_PASSWORD: wikijsrocks
      POSTGRES_USER: wikijs
    logging:
      driver: none
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/postgresql/data
  wiki:
    image: ghcr.io/requarks/wiki:2
    depends_on:
      - db
    init: true
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs
      DB_PASS: wikijsrocks
      DB_NAME: wiki
    restart: unless-stopped
    ports:
      - "80:3000"
volumes:
  db-data:

실행하기 전에 POSTGRES_PASSWORD과 DB_PASS을 함께 변경해야 한다. 두 값은 하나의 자격 증명이며, 예시 값은 공개되어 있기 때문이다. 태그는 의도적으로 ghcr.io/requarks/wiki:2에 고정되어 있다. 문서에서는 latest을 사용하지 말 것을 권장한다. major version을 변경하면 실행 중인 인스턴스의 데이터베이스 스키마가 바뀌기 때문이다.

실행할 버전은 Version 2 계열이다. 2026년 10월 기준으로 가장 최신인 Version 2 릴리스는 2.5.316이며, 2026년 10월에 릴리스되었다. 이제 Version 2 릴리스는 별도의 requarks/wiki-v2 repository에서 게시되며, :2 이미지 태그가 계속 이 릴리스를 가리킨다. Version 3은 public beta 단계다. 설치 문서에 따르면 이 버전의 이미지는 3.0.0-beta으로 태그되며, beta 단계가 끝날 때까지 일반적인 3 및 3.0 태그는 작동하지 않는다. Version 3은 production 대상이 아니라 preview로 다뤄야 한다. Release 2.5.316에는 나중에 콘텐츠를 Version 3으로 옮길 수 있는 export utility도 추가되었다.

처음 로드하면 Wiki.js가 브라우저에서 진행되는 설정 절차를 표시하고 administrator account를 생성한다. 설정을 완료하기 전에는 해당 포트에 접근할 수 있는 누구에게나 이 wizard가 표시된다. 따라서 firewall을 열기 전에 reverse proxy와 TLS(transport layer security) 뒤에 서비스를 배치해야 한다. 서버에서 이 서비스 외에 여러 서비스를 운영한다면, 별도의 hostname을 사용하는 wiki는 여러 Docker 앱 앞에 Traefik 배치 구성 뒤에 자연스럽게 둘 수 있다.

사람들이 Wiki.js를 선택하는 이유는 editor 선택의 폭이다. 하나의 인스턴스에서 Markdown 페이지, visual editor 페이지, raw HTML 페이지 및 AsciiDoc 페이지를 나란히 운영할 수 있다. 변환하고 싶지 않은 형식으로 작성된 기존 콘텐츠를 가져올 때 유용하다. 반면 하나의 wiki에 네 가지 사내 스타일이 생길 수도 있다. 따라서 첫날에 default editor를 결정하고 그 내용을 문서로 남겨야 한다.

Outline: 최고의 편집기, 가장 무거운 필수 구성 요소

Outline은 사람들이 상용 노트 도구와 같은 느낌을 원할 때 흔히 언급하는 도구입니다. 이 애플리케이션은 Node.js 기반이며, 2026년 10월 17일 기준 최신 릴리스는 2026년 10월 12일에 배포된 1.11.0 버전입니다. 샘플 환경 파일에는 필요한 구성 요소가 나열되어 있습니다. DATABASE_URL를 통한 PostgreSQL, REDIS_URL를 통한 Redis, 두 개의 임의 보안 키, 그리고 외부에서 접근 가능한 URL가 필요합니다.

openssl rand -hex 32
openssl rand -hex 32

해당 명령을 두 번 실행하여 두 값을 모두 보관하십시오. 첫 번째 값은 SECRET_KEY가 되고, 두 번째 값은 UTILS_SECRET가 됩니다. 환경 파일의 핵심 구성은 다음과 같습니다.

NODE_ENV=production
URL=https://docs.example.com
PORT=3000
SECRET_KEY=<first openssl value>
UTILS_SECRET=<second openssl value>
DATABASE_URL=postgres://outline:change_me@postgres:5432/outline
PGSSLMODE=disable
REDIS_URL=redis://redis:6379
FILE_STORAGE=local
FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data

PGSSLMODE=disable은 데이터베이스가 동일한 머신이나 동일한 Docker 네트워크에 있을 때만 올바르게 작동합니다. 네트워크를 통해 데이터베이스에 접근하는 경우 이 설정을 제외하십시오. 그렇지 않으면 연결이 평문으로 전송됩니다. 이제 첨부 파일을 위해 반드시 객체 스토리지를 사용할 필요는 없습니다. FILE_STORAGE=local은 업로드 파일을 상위 디렉터리에 기록하며, 이 디렉터리는 컨테이너가 쓸 수 있는 볼륨이어야 하고 백업 대상에 포함되어야 합니다. 파일을 S3 호환 버킷에 저장하려면 AWS_* 값을 사용하여 FILE_STORAGE=s3를 설정하십시오.

이제 사람들이 놀라워하는 부분입니다. Outline은 자체적인 사용자 이름 및 비밀번호 로그인 기능을 제공하지 않습니다. 샘플 설정 파일에는 타사 로그인 자격 증명이 필수라고 명시되어 있습니다. "설치가 정상적으로 작동하려면 이 중 최소 하나가 필요하며, 그렇지 않으면 로그인 옵션이 제공되지 않습니다." 문서화된 제공업체로는 Google, Slack, Microsoft Entra, Discord가 있으며, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_AUTH_URI, OIDC_TOKEN_URI, OIDC_USERINFO_URI를 통해 일반적인 OpenID Connect(OIDC) 서버를 사용할 수 있습니다.

따라서 Outline의 실제 운영 비용은 Outline, PostgreSQL, Redis, 그리고 ID 제공업체를 합친 것입니다. 이미 팀에서 Google Workspace나 Microsoft Entra를 사용하여 로그인하고 있다면 마지막 구성 요소를 설정하는 데 10분이면 충분하며, Outline은 매우 매력적인 선택지가 됩니다. 그렇지 않다면 Keycloak이나 Authentik과 같은 서비스를 직접 호스팅해야 하며, 이는 패치하고 백업해야 할 두 번째 서비스가 됩니다. 메모리 예산을 적절히 책정하십시오. Outline의 자체 가이드에 따르면 WEB_CONCURRENCY으로 설정된 웹 프로세스당 약 512 MB의 메모리가 필요하며, 이는 데이터베이스와 Redis 사용량과는 별개입니다.

각 서비스의 읽기 권한 관리 방식

BookStack은 기본적으로 로컬 이메일 및 비밀번호 계정을 제공하며, 대안으로 LDAP, SAML2, OIDC를 지원합니다. 권한은 역할별로 설정하며, 특정 셸프(shelf), 북(book), 챕터(chapter) 또는 페이지(page) 단위로 재정의할 수 있습니다. 계층 구조가 고정되어 있어 권한은 예측 가능한 방식으로 하위 항목에 상속됩니다.

Wiki.js 역시 로컬 계정을 기본으로 제공하며, 관리자 영역에서 활성화할 수 있는 다양한 인증 전략을 추가로 지원합니다. 페이지 규칙은 경로 패턴에 따라 접근을 허용하거나 거부합니다. 이 방식은 강력하지만 설정 오류가 발생하기 쉽습니다. 예를 들어 ops/* 경로에 대해 작성한 규칙은 나중에 해당 경로 아래에 생성하는 모든 페이지에 자동으로 적용되기 때문입니다.

Outline은 권한 관리 책임을 전적으로 외부로 위임합니다. 멤버십은 ID 공급자(identity provider)를 따르며, Outline 내부에서는 컬렉션(collection)과 그룹(group) 단위로 접근을 제어합니다. 직원이 퇴사할 때 로컬 계정이 남지 않으므로, 이미 계정 프로비저닝을 관리하고 있는 ID 공급자를 사용하는 경우 큰 이점이 있습니다.

각 서비스의 검색 작동 방식

검색 기능은 위키가 제 역할을 다하게 할지, 아니면 잊힌 파일들의 폴더로 전락하게 할지를 결정합니다.

BookStack은 데이터베이스를 검색하며, 사용자가 1분 안에 익힐 수 있는 쿼리 언어를 제공합니다. "london meeting"과 같이 문구를 따옴표로 묶으면 해당 정확한 문자열을 검색합니다. 대괄호는 태그를 검색합니다. [location=london]은 태그 이름, 값 또는 둘 다를 기준으로 일치 항목을 찾으며, !=, >=, like을 포함한 비교 연산자를 지원합니다. 중괄호는 {created_after:2016-12-30}와 같이 메타데이터를 필터링합니다. 정확한 용어, 태그, 필터 용어 앞에 -을 붙여 부정 검색을 수행할 수 있습니다. BookStack은 한 쿼리에 포함할 수 있는 각 유형의 용어 개수를 제한하므로, 너무 긴 쿼리는 잘린 뒤 실행됩니다.

Wiki.js는 검색을 플러그인 가능한 모듈로 처리합니다. 문서화된 엔진으로는 기본 데이터베이스 엔진, PostgreSQL 엔진, Elasticsearch, Algolia, AWS CloudSearch, Azure Search가 있습니다. 기본 엔진은 수백 페이지 규모의 위키에 적합합니다. PostgreSQL을 운영 중이라면 관리자 영역에서 PostgreSQL 엔진으로 전환하십시오. 단순 일치 방식 대신 데이터베이스 자체의 전체 텍스트 인덱스를 사용하기 때문입니다. Elasticsearch는 두 번째 검색 서비스를 운영하고 패치하는 수고를 감수할 만큼 위키 규모가 클 때만 사용하십시오.

Outline은 PostgreSQL의 전체 텍스트 인덱스를 검색합니다. 선택할 엔진이나 조정할 설정은 없으며, 업로드된 문서 내부의 텍스트까지 검색합니다. 1,000에서 3,000건 정도의 문서를 다루는 팀 위키라면 이 세 가지 서비스 중 가장 관리가 간편합니다. 다만 검색 속도가 충분히 빠르지 않을 경우 사용자가 조정할 수 있는 수단은 없습니다.

어떤 도구가 적합한가

오늘 오후 당장 위키를 운영해야 하고, 구조보다는 콘텐츠 자체에 집중하고 싶다면 BookStack을 선택하십시오. 이 도구는 구성 요소가 가장 적어 PHP 애플리케이션 하나와 MySQL 데이터베이스 하나만 있으면 됩니다. 내부 운영 매뉴얼이나 고객용 문서화에 적합하며, 작성자 대부분이 엔지니어가 아닌 팀에 알맞습니다. 또한 전체 상태가 데이터베이스 덤프 하나와 업로드 디렉터리로 구성되므로 세 가지 도구 중 백업이 가장 쉽습니다.

특정 편집기나 다른 도구에서 제공하지 않는 인증 방식이 필요하거나, 기존의 방대한 Markdown 또는 AsciiDoc 문서를 가져오면서 경로 구조를 유지해야 한다면 Wiki.js를 선택하십시오. 더 무거운 스택을 운영해야 한다는 점을 감수하고, 메이저 버전 태그를 고정하여 사용하십시오.

글쓰기의 품질이 가장 중요하고, 위키가 대중이 아닌 팀 내부용이며, 이미 사용 중인 ID 공급자(identity provider)가 있다면 Outline을 선택하십시오. 사용자가 실제로 즐겨 사용하는 편집기를 제공하여 그만한 가치를 보상합니다. 다만, 처음으로 시도하는 자체 호스팅 애플리케이션으로는 권장하지 않습니다.

위 세 가지 중 적합한 것이 없다면, 콘텐츠 유형이 맞지 않을 가능성이 큽니다. 스캔한 송장이나 계약서는 위키가 아니라 Paperless-ngx와 같은 문서 관리 시스템에 저장해야 합니다. 이를 억지로 위키에 넣으려 하면 많은 위키가 결국 방치되는 결과를 낳습니다. 또 다른 흔한 불일치는 위키가 아니라 문서, 표, 화이트보드를 하나의 캔버스에서 다루는 작업 공간을 원하는 경우입니다. 이럴 때는 위 세 가지 도구보다 자체 호스팅 AFFiNE 작업 공간이 더 적합합니다. 서버에 올릴 만한 다른 도구들에 대한 더 넓은 시야를 원한다면 2026년 자체 호스팅 추천 목록을 확인하십시오.

사이징 및 백업

세 가지 서비스 모두 소형 VPS에서 구동할 수 있지만, 각 서비스의 백엔드 구성에 따라 실제 필요한 최소 사양은 달라집니다. BookStack은 애플리케이션 프로세스 하나와 MySQL로 구성됩니다. Wiki.js는 Node 프로세스와 PostgreSQL을 사용합니다. Outline은 Node 프로세스, PostgreSQL, Redis를 사용하며, 보통 별도의 ID 공급자(identity provider)를 함께 운영해야 하므로 더 많은 메모리를 할당해야 합니다.

데이터베이스와 업로드 파일을 함께 백업하고, 백업을 실제로 사용하기 전에 반드시 테스트용 인스턴스에 복원해 보아야 합니다. 복원해 보지 않은 위키 백업은 그저 추측일 뿐입니다. BookStack의 경우 mysqldump과 /config 볼륨을 백업해야 합니다. Wiki.js와 Outline은 pg_dump와 데이터 볼륨을 백업해야 하며, Outline의 경우 FILE_STORAGE_LOCAL_ROOT_DIR에 있는 데이터도 함께 백업해야 합니다.

FAQ

가장 설치하기 쉬운 self-hosted 위키는 무엇입니까?

BookStack입니다. MySQL 데이터베이스를 사용하는 단일 PHP 애플리케이션이며, Ubuntu 24.04에서 Apache, MySQL 8.0, PHP 8.3을 한 번에 설정하는 설치 스크립트를 프로젝트에서 제공합니다. 컨테이너 이미지는 APP_KEY와 데이터베이스 인증 정보만 필요합니다. Wiki.js는 Node runtime과 PostgreSQL server를 추가로 사용하고, Outline은 여기에 Redis와 외부 identity provider까지 추가합니다.

Google 또는 다른 SSO provider 없이 Outline을 사용할 수 있습니까?

아니요. Outline에는 로컬 username 및 password login이 없습니다. 샘플 설정에는 하나 이상의 third party sign-in provider가 필요하다고 명시되어 있습니다. 그렇지 않으면 sign-in option을 전혀 사용할 수 없습니다. Google, Slack, Microsoft Entra, Discord 또는 self-hosted Keycloak이나 Authentik 같은 generic OpenID Connect server를 사용할 수 있습니다. 해당 provider를 운영하는 비용도 Outline 운영 비용에 포함됩니다.

Wiki.js 3과 Wiki.js 2 중 어느 것을 설치해야 합니까?

Version 2입니다. 2026년 10월 기준으로 최신 version 2 release는 2026년 10월에 나온 2.5.316이며, version 3은 아직 beta이고 이미지에 3.0.0-beta tag가 포함되어 있습니다. 실행 중인 instance에서 major version을 변경하면 database schema가 변경되므로, 이미지를 latest가 아니라 ghcr.io/requarks/wiki:2에 고정해야 합니다.

검색 기능이 가장 좋은 것은 무엇입니까?

각 제품은 서로 다른 방식으로 강점을 가집니다. BookStack은 exact phrase, [location=london] 같은 tag filter, {created_after:2016-12-30} 같은 metadata filter를 사용하는 query language를 제공합니다. 이러한 term에는 앞에 -를 붙여 모두 제외할 수 있습니다. Outline은 별도 configuration이 필요 없으며 업로드한 file 내부의 text를 검색합니다. Wiki.js는 검색 engine을 선택할 수 있어 가장 세밀하게 조정할 수 있습니다. PostgreSQL engine은 위키가 수백 개의 page를 넘어서는 즉시 전환할 가치가 있습니다.

나중에 한 제품에서 다른 제품으로 content를 옮길 수 있습니까?

부분적으로 가능하지만 수작업이 필요합니다. 세 제품 모두 Markdown을 export하고 import하므로 page text는 대체로 유지됩니다. 그러나 structure는 제대로 유지되지 않습니다. BookStack의 book과 chapter에 해당하는 구조가 Outline의 nested document에는 없으며, Wiki.js의 path도 BookStack의 고정 hierarchy에 매핑되지 않습니다. Attachment, permission, page history가 손실될 가능성이 가장 높은 항목입니다. 따라서 migration을 결정하기 전에 일부 content를 export하여 이러한 항목을 확인해야 합니다.