Outline – 팀을 위한 오픈소스 지식 베이스 & 위키 Docker 설치 가이드

---

개요

Outline은 팀을 위한 모던한 오픈소스 지식 베이스(Knowledge Base) 및 위키 소프트웨어입니다. Notion, Confluence의 셀프 호스팅 대안으로, 아름다운 UI와 실시간 협업 기능을 제공합니다. Node.js와 React로 개발되어 빠른 성능을 자랑하며, 마크다운과 슬래시 커맨드를 지원합니다.

GitHub: https://github.com/outline/outline
공식 사이트: https://www.getoutline.com
GitHub Stars: 29,000+
라이선스: BSL 1.1 (Business Source License)

---

Outline이란?

Outline은 팀의 내부 문서화를 위한 지식 관리 플랫폼입니다. 제품 스펙, 온보딩 문서, 회의록, FAQ, 운영 매뉴얼 등을 체계적으로 관리할 수 있습니다.

핵심 컨셉

• Collections: 문서를 주제별로 그룹화하는 컬렉션
• Documents: 마크다운 기반의 중첩 가능한 문서
• Real-time Collaboration: 실시간 동시 편집
• Search: 강력한 전문 검색 기능

---

주요 특징

1. 직관적인 편집 경험

• 마크다운 지원 및 실시간 미리보기
• 슬래시(/) 커맨드로 빠른 포맷팅
• 이미지, 비디오, 코드 블록 임베드
• Figma, Loom, Google Docs 등 외부 콘텐츠 삽입

2. 실시간 협업

• 여러 사용자가 동시에 문서 편집
• 댓글 및 스레드로 토론
• 이모지 리액션
• @멘션으로 팀원 호출

3. 강력한 검색

• 전문(Full-text) 검색
• 필터 및 정렬 기능
• 최근 문서, 업데이트된 문서 빠른 접근
• AI 기반 질문 응답 (Enterprise)

4. 보안 및 권한 관리

• SSO (SAML, OIDC) 지원
• 2FA (이중 인증)
• 역할 기반 접근 제어 (RBAC)
• 컬렉션/문서별 세분화된 권한 설정

5. 다양한 통합

• Slack, Google, Microsoft 로그인
• Slack 알림 연동
• Figma, Loom, Miro 임베드
• Zapier, API 연동
• Confluence 마이그레이션 지원

6. 기타 기능

• 버전 히스토리 및 복원
• 문서 내보내기 (Markdown, PDF, HTML)
• 다국어 지원 (17개 언어)
• RTL (오른쪽에서 왼쪽) 언어 지원
• PWA 지원

---

유사 도구 비교

항목	Outline	Notion	Confluence	BookStack	Wiki.js
호스팅	셀프/클라우드	클라우드	클라우드/서버	셀프 호스팅	셀프 호스팅
가격 (셀프)	무료	–	유료	무료	무료
가격 (클라우드)	$10/user/월~	$10/user/월~	$5.50/user/월~	–	–
실시간 협업	✅ 강력	✅ 강력	✅ 지원	❌ 미지원	❌ 미지원
마크다운	✅	✅	제한적	✅	✅
SSO/SAML	✅	유료	✅	✅	✅
API	✅	✅	✅	✅	✅
UI/UX	모던/깔끔	모던/유연	복잡	심플	모던
학습 곡선	낮음	중간	높음	낮음	중간
설치 난이도	높음	–	중간	낮음	중간

언제 Outline을 선택할까?

Outline이 적합한 경우:

• 팀 내부 문서화 및 지식 관리가 필요할 때
• Notion/Confluence 대안으로 셀프 호스팅이 필요할 때
• 모던하고 깔끔한 UI를 원할 때
• 실시간 협업이 중요할 때
• Slack, Google 등 기존 도구와 연동이 필요할 때

다른 도구가 적합한 경우:

• 간단한 설치를 원한다면 → BookStack (PHP 기반, 설치 쉬움)
• 데이터베이스 기능이 필요하다면 → Notion
• 복잡한 권한/워크플로우가 필요하다면 → Confluence
• 개인용 노트 앱이 필요하다면 → Memos, Obsidian

---

시스템 요구사항

필수 구성요소

구성요소	설명
PostgreSQL	데이터베이스 (필수)
Redis	캐시 및 세션 관리 (필수)
파일 스토리지	로컬 또는 S3 호환 스토리지
인증 제공자	Slack, Google, OIDC 등 (최소 1개 필수)

권장 사양

• CPU: 2코어 이상
• RAM: 2GB 이상 (권장 4GB)
• 저장 공간: 10GB 이상 (콘텐츠에 따라 증가)

---

Docker Compose 설치

Outline은 설치가 다소 복잡합니다. 인증 제공자(OAuth) 설정이 필수이며, 여러 서비스가 함께 동작해야 합니다.

사전 준비

1. 도메인: outline.example.com (HTTPS 필수)
2. 인증 제공자: Slack, Google, 또는 자체 OIDC 서버 (Keycloak 등)
3. Docker 및 Docker Compose 설치

1. 디렉토리 생성

mkdir -p ~/docker/outline
cd ~/docker/outline

2. 시크릿 키 생성

# SECRET_KEY 생성 (32바이트 hex)
openssl rand -hex 32

# UTILS_SECRET 생성
openssl rand -hex 32

3. docker-compose.yml 작성

services:
  outline:
    image: docker.getoutline.com/outlinewiki/outline:latest
    container_name: outline
    env_file: ./docker.env
    ports:
      - "3000:3000"
    volumes:
      - ./data:/var/lib/outline/data
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    container_name: outline-postgres
    environment:
      POSTGRES_USER: outline
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: outline
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U outline -d outline"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: outline-redis
    volumes:
      - ./redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres-data:
  redis-data:
  data:

4. docker.env 파일 작성

# ─────────────────────────────────────────────────────────────
# 필수 설정
# ─────────────────────────────────────────────────────────────

# 시크릿 키 (openssl rand -hex 32로 생성)
SECRET_KEY=your_secret_key_here
UTILS_SECRET=your_utils_secret_here

# 데이터베이스 연결
DATABASE_URL=postgres://outline:your_postgres_password@outline-postgres:5432/outline
PGSSLMODE=disable

# Redis 연결
REDIS_URL=redis://outline-redis:6379

# 외부 접속 URL (HTTPS 필수)
URL=https://outline.example.com
PORT=3000

# ─────────────────────────────────────────────────────────────
# 파일 스토리지 설정
# ─────────────────────────────────────────────────────────────

# 로컬 스토리지 사용
FILE_STORAGE=local
FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
FILE_STORAGE_UPLOAD_MAX_SIZE=26214400

# ─────────────────────────────────────────────────────────────
# 인증 설정 (최소 1개 필수 - Slack, Google, OIDC 중 선택)
# ─────────────────────────────────────────────────────────────

# [옵션 1] Slack 인증
# SLACK_CLIENT_ID=your_slack_client_id
# SLACK_CLIENT_SECRET=your_slack_client_secret

# [옵션 2] Google 인증
# GOOGLE_CLIENT_ID=your_google_client_id
# GOOGLE_CLIENT_SECRET=your_google_client_secret

# [옵션 3] OIDC 인증 (Keycloak, Authentik 등)
# OIDC_CLIENT_ID=your_oidc_client_id
# OIDC_CLIENT_SECRET=your_oidc_client_secret
# OIDC_AUTH_URI=https://your-idp.com/auth
# OIDC_TOKEN_URI=https://your-idp.com/token
# OIDC_USERINFO_URI=https://your-idp.com/userinfo
# OIDC_DISPLAY_NAME=Login with SSO

# ─────────────────────────────────────────────────────────────
# 선택적 설정
# ─────────────────────────────────────────────────────────────

# 기본 언어
DEFAULT_LANGUAGE=ko_KR

# 사용자 초대 허용
ENABLE_UPDATES=true

# 강제 HTTPS
FORCE_HTTPS=true

# 디버그 모드 (프로덕션에서는 false)
DEBUG=false

# 로그 레벨
LOG_LEVEL=info

5. 파일 권한 설정

# data 디렉토리 생성 및 권한 설정
mkdir -p data
chown -R 1001:1001 data

6. 컨테이너 실행

docker compose up -d

7. 로그 확인

docker compose logs -f outline

---

인증 제공자 설정

Outline은 자체 회원가입을 지원하지 않으며, 반드시 외부 인증 제공자가 필요합니다.

Slack 인증 설정

1. Slack API에서 새 앱 생성
2. OAuth & Permissions에서 Redirect URL 추가: https://outline.example.com/auth/slack.callback
3. Scopes 추가: identity.basic, identity.email, identity.avatar
4. Client ID와 Client Secret을 docker.env에 입력

Google 인증 설정

1. Google Cloud Console에서 프로젝트 생성
2. OAuth 2.0 클라이언트 ID 생성
3. 승인된 리디렉션 URI 추가: https://outline.example.com/auth/google.callback
4. Client ID와 Client Secret을 docker.env에 입력

Keycloak (OIDC) 연동

기존에 Keycloak을 사용 중이라면 OIDC 설정을 활용할 수 있습니다.

1. Keycloak에서 새 Client 생성
2. Access Type: confidential
3. Valid Redirect URIs: https://outline.example.com/*
4. docker.env에 OIDC 설정 입력

---

Nginx 리버스 프록시 설정

server {
    listen 80;
    server_name outline.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name outline.example.com;

    ssl_certificate /etc/letsencrypt/live/outline.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/outline.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

---

컨테이너 관리

기본 명령어

# 시작
docker compose up -d

# 중지
docker compose down

# 로그 확인
docker compose logs -f outline

# 재시작
docker compose restart

# 업데이트
docker compose pull
docker compose up -d

데이터베이스 마이그레이션

업데이트 후 자동으로 실행되지만, 수동 실행이 필요한 경우:

docker compose exec outline yarn db:migrate

---

데이터 백업

PostgreSQL 백업

# 백업
docker exec outline-postgres pg_dump -U outline outline > outline-backup-$(date +%Y%m%d).sql

# 복원
cat outline-backup.sql | docker exec -i outline-postgres psql -U outline -d outline

전체 백업 (파일 포함)

# 컨테이너 중지
docker compose down

# 전체 디렉토리 백업
tar -czvf outline-full-backup-$(date +%Y%m%d).tar.gz \
  postgres-data/ \
  redis-data/ \
  data/ \
  docker.env \
  docker-compose.yml

# 컨테이너 재시작
docker compose up -d

---

트러블슈팅

1. 인증 오류

Error: No authentication provider configured

해결: docker.env에 최소 1개의 인증 제공자(Slack, Google, OIDC) 설정 필요

2. 파일 업로드 실패

Error: EACCES: permission denied

해결:

chown -R 1001:1001 data

3. 데이터베이스 연결 실패

해결:

• PostgreSQL 컨테이너 상태 확인
• DATABASE_URL 형식 확인
• 네트워크 연결 확인

4. HTTPS 리다이렉트 루프

해결:

• FORCE_HTTPS=true 설정 확인
• 리버스 프록시의 X-Forwarded-Proto 헤더 설정 확인

---

활용 팁

1. 컬렉션 구조 예시

📁 Engineering
  ├── 📄 Architecture Overview
  ├── 📄 API Documentation
  └── 📁 Runbooks
      ├── 📄 Deployment Guide
      └── 📄 Incident Response

📁 Product
  ├── 📄 PRD Template
  └── 📄 Release Notes

📁 HR & Onboarding
  ├── 📄 Employee Handbook
  └── 📄 New Hire Checklist

2. 슬래시 커맨드 활용

• /heading – 제목 추가
• /bullet – 불릿 리스트
• /checkbox – 체크박스
• /code – 코드 블록
• /image – 이미지 삽입
• /embed – 외부 콘텐츠 임베드

3. 키보드 단축키

단축키	기능
Ctrl/Cmd + K	링크 추가
Ctrl/Cmd + B	굵게
Ctrl/Cmd + I	기울임
Ctrl/Cmd + Shift + S	취소선
Ctrl/Cmd + /	단축키 목록

---

마무리

Outline은 설치가 다소 복잡하지만, 한번 구축하면 팀의 지식 관리를 위한 강력한 도구가 됩니다. 특히 Notion이나 Confluence를 사용하다가 셀프 호스팅으로 전환하려는 팀에게 좋은 선택입니다.

추천 대상

• 팀 내부 문서화가 필요한 스타트업/기업
• Notion/Confluence의 셀프 호스팅 대안을 찾는 팀
• 실시간 협업이 중요한 원격 근무 팀
• 데이터 주권이 중요한 조직
• 모던한 UI/UX를 선호하는 팀

주의사항

• 인증 제공자(OAuth) 설정이 필수
• HTTPS가 필수 (HTTP로는 동작하지 않음)
• 설치 난이도가 높은 편 (BookStack 대비)

---

참고 자료

• Outline 공식 문서
• Outline GitHub
• Outline Changelog
• Docker 설치 가이드

---