Outline Wiki 자체 구축 가이드 (1): Docker 설치, Gitea OIDC 및 AI 지식 베이스 준비

이번 글에서 해결하고자 하는 문제

회사의 개발 팀에서 내부 지식 베이스(Knowledge Base)를 구축하고 싶지만, 동시에 AI 지원도 필요할 때 흔히 발생하는 페인 포인트(Pain Point)는 다음과 같습니다:

• 문서 데이터가 외부로 유출되어 상업적 기밀이 누설되는 것을 방지하기 위해, 데이터를 외부로 노출하지 않고 자신의 기기에 남겨두고 싶음.
• AI 기능을 추가하고 싶은데, Notion처럼 비용($$)을 지불해야 하거나, 혹은 Docmost처럼 직접 구축해야 하는 번거로움이 있음.
• Outline Wiki는 설치가 매우 어려움. August는 한 번 실패했으며, 결국 Claude Opus 4.8의 도움을 받아 성공함.

본 노트에서는 Docker Compose 파일을 사용하여 Outline과 필요한 PostgreSQL, Redis, Caddy를 모두 포함하여 설치하고, 위에서 언급한 문제들을 한 번에 해결하는 방법을 다룹니다.

또한, 본문의 기본 설정에 대해 먼저 설명하겠습니다:

1. 로컬 환경에 Docker가 이미 설치되어 있음.
2. 내부 포트(Internal PORT)는 3002이며, 외부 포트(External PORT)는 3001임.

Outline + AI에 대한 보충 설명:

자체 구축 버전의 Outline에는 내장된 "AI Answers" 기능이 없으며, 인터넷에서 흔히 보이는 OPENAI_API_KEY는 자체 구축 버전에서 무효합니다. Outline에 AI를 추가하고 싶다면, MCP를 통해 외부 연결을 하여 Claude / Codex가 Outline의 API를 통해 조작할 수 있도록 하는 것이 정답입니다 (방법은 다음 글에서 작성 예정).

단계 1: Gitea 설치

첫 번째 관리자 계정은 Gitea를 통해 로그인해야 하므로, 먼저 Gitea가 설치되어 있어야 합니다.

Gitea 자체도 Docker로 구축할 수 있으며, 이 부분은 이전에 August가 작성한 다음 글을 직접 참고하십시오:

Gitea 설치하기.

Gitea에 정상적으로 로그인할 수 있다면 다음 단계로 넘어갈 수 있습니다.

Outline은 반드시 Gitea일 필요는 없으며, OIDC와 호환되는 모든 공급업체(Keycloak, Authentik, Google 등)가 가능합니다. 차이점은 OIDC_* 관련 URL 값들뿐입니다.

단계 2: Gitea에서 Client ID 및 Secret 가져오기

Outline은 OIDC 로그인을 사용하므로, Gitea에서 "OAuth2 애플리케이션"을 생성하여 Client ID와 Client Secret을 받아야 합니다.

Gitea에 접속한 후, **설정 (Settings) → 애플리케이션 (Applications)**으로 이동하여 "OAuth2 애플리케이션 관리" 섹션을 찾습니다.

Gitea의 "설정 → 애플리케이션" 페이지에서 "OAuth2 애플리케이션 관리" 생성 양식

두 가지 필드를 채워야 합니다:

• 애플리케이션 이름: Outline Wiki Login과 같이 무엇을 위한 것인지 기억할 수 있는 이름을 입력합니다.
• 리다이렉트 URI (Redirect URI): 외부로 노출되는 포트에 인증서가 적용되어야 하며, 본문에서는 3001을 사용합니다.

예를 들어 호스트 IP가 192.168.11.111이라면, https://192.168.11.111:3001/auth/oidc.callback을 입력합니다. 이 IP와 포트 번호는 나중에 Compose 파일의 URL= 설정과 완전히 일치해야 합니다.

Gitea OAuth2 애플리케이션 양식, 애플리케이션 이름과 리다이렉트 URI 입력 (중요한 점은 Redirect URI가 /auth/oidc.callback으로 끝나야 한다는 것입니다)

"애플리케이션 생성"을 누르면 Gitea에 Client ID와 Client Secret이 표시됩니다.

Gitea 생성이 완료된 후 표시되는 Client ID 및 Client Secret 화면입니다.

주의할 점은, Client Secret은 이번 한 번만 전체 내용이 표시되므로, 먼저 복사하여 저장해 두어야 한다는 것입니다. 잠시 후 Compose의 OIDC_CLIENT_ID와 OIDC_CLIENT_SECRET에 입력할 예정입니다.

단계 3-1: Outline Wiki 설치: Windows 버전

Windows에서는 Docker Desktop을 사용하며, 여기서는 첨부 파일을 저장하기 위해 (Docker가 관리하는) 이름이 지정된 볼륨(Named Volume)을 사용하여 가장 단순하게 시작합니다.

먼저 빈 폴더를 하나 생성한 다음, 아래의 2개 파일을 넣을 것입니다.

Caddyfile

폴더 내에 Caddyfile이라는 이름의 파일을 새로 생성합니다.

Caddyfile은 "외부에는 HTTPS를 제공하고, 트래픽을 Outline으로 전달"하는 역할을 담당합니다.

파일 내용을 아래와 같이 복사하여 붙여넣은 후, 192.168.11.111을 사용 중인 Windows 호스트의 로컬 네트워크(LAN) IP로 변경하세요:

{
  default_sni 192.168.11.111
}
...

• tls internal: Caddy가 자체적으로 인증서를 서명합니다. 로컬 네트워크 IP를 사용하기 때문에 원래 정식 인증서를 신청할 수 없으므로, 자체 서명(Self-signed) 인증서로도 충분합니다.
• 3001은 외부 포트(External Port)이고, outline:3002는 Outline 컨테이너 내부 포트(Internal Port)입니다. 두 포트의 역할이 다르므로 동일하게 작성하지 않도록 주의하세요.

docker-compose.yml

폴더 내에 docker-compose.yml이라는 이름의 파일을 추가로 생성합니다.

파일 내용을 아래와 같이 복사하여 붙여넣으세요:

# =============================================================================
# Outline Wiki — Docker Compose 튜토리얼 예제
# =============================================================================
...

그 다음 모든 <...> 부분을 자신의 값으로 교체해야 하며, 다음 항목들을 수정해야 합니다:

• SECRET_KEY, UTILS_SECRET: 터미널을 열고 openssl rand -hex 32를 두 번 실행하여 32바이트 무작위 문자열을 생성합니다. 만약 openssl이 없다면, Claude나 ChatGPT 같은 AI를 사용하여 대화창에서 2세트를 생성해 달라고 요청하여 사용하세요.
• DATABASE_URL 및 POSTGRES_PASSWORD: 양쪽의 비밀번호가 일치해야 합니다.
• URL: https://<당신의IP>:3001을 입력합니다. IP는 Caddyfile과 동일해야 합니다.
• OIDC_CLIENT_ID, OIDC_CLIENT_SECRET: 앞서 Gitea에서 가져온 값을 입력합니다.
• OIDC_AUTH_URI / OIDC_TOKEN_URI / OIDC_USERINFO_URI: <OIDC_HOST> 부분을 Gitea 주소로 변경합니다.
• (선택 사항) SMTP: 초대 메일이나 매직 링크(magic-link)를 보내려면 설정해야 합니다.

실행

docker-compose.yml 파일이 있는 폴더에서 터미널을 엽니다:

docker compose up -d

Outline을 처음 실행할 때는 데이터베이스 마이그레이션 (Migration)이 자동으로 진행되므로, 10여 초 정도 더 기다려야 합니다.

Outline이 정상적으로 올라온 것을 확인했다면, 브라우저에서 https://<당신의IP>:3001을 엽니다.

브라우저에 "연결이 비공개로 설정되어 있지 않습니다 / 안전하지 않음" 경고가 뜰 것입니다.

이는 tls internal이 자체 서명 인증서를 사용하기 때문에 발생하는 정상적인 현상입니다. "고급 → 계속 진행"을 클릭하면 Outline에 접속할 수 있습니다.

접속 후 Continue with Gitea를 클릭하여 Gitea 계정으로 로그인합니다. 가장 처음 로그인하는 사람이 관리자(Admin)가 됩니다.

이후의 멤버들은 Outline 관리자 페이지에서 이메일로 초대할 수 있습니다 (이것이 위에서 SMTP를 설정해야 했던 이유입니다).

단계 3-2: Outline Wiki 설치: Ubuntu 버전

Ubuntu 버전은 Windows 버전과 거의 동일하며, 딱 두 가지 차이점만 있습니다:

1. 첨부 파일(Attachment)을 bind mount(./data)로 변경: 첨부 파일이 프로젝트 폴더에 직접 저장되므로, 폴더 전체를 이동하거나 백업/복사하여 간편하게 옮길 수 있습니다. 이름이 지정된 볼륨(Named Volume)처럼 tar 명령어로 추출할 필요가 없습니다.
2. OIDC용 Gitea는 다른 머신에 있어도 되며, 해당 Ubuntu 머신에서 접속만 가능하면 됩니다.

파일

마찬가지로 두 개의 파일가 필요합니다: docker-compose.yml과 Caddyfile입니다.

Caddyfile 내용 (IP를 본인의 Ubuntu 호스트 IP로 변경하세요):

{
  default_sni 192.168.11.111
}
...

docker-compose.yml의 내용은 아래 내용을 복사하여 붙여넣으세요:

# =============================================================================
# Outline Wiki — Ubuntu 단일 호스트 배포 버전 (튜토리얼 예시)
# =============================================================================
...

수정해야 할 부분(예: 키(Key), DB, OIDC, SMTP 등)은 Windows 버전의 작성 방식과 완전히 동일합니다.

실행

docker-compose.yml이 있는 폴더에서 터미널을 엽니다:

docker compose up -d

확인 및 로그인 절차는 Windows 버전과 동일합니다: 브라우저에서 https://<본인의IP>:3001을 열고, 인증서 경고가 뜨면 "계속 진행"을 클릭한 뒤 Gitea를 사용하여 로그인하세요.

결론

위의 단계들을 따라 하면, 완전 자가 구축 + 무료 + MCP를 통해 AI와 연결 가능한 Outline Wiki 환경을 갖추게 됩니다.

MCP를 사용하여 Claude, Codex와 연결하는 방법은 다음 글에서 설명하겠습니다.