시작하기

원문 보기 위키 갱신 2026.10.07

시작하기 (이전 프론트엔드 시스템)

참고

이 문서는 여전히 이전 프론트엔드 시스템을 사용하는 Backstage 앱을 위한 것이에요. 앱이 새 프론트엔드 시스템을 사용한다면 현재 가이드를 대신 읽어 주세요.

출처: 문서

본문

참고

TechDocs는 Backstage에서 플러그인으로 동작하며 기본으로 설치되어 함께 제공되므로, TechDocs를 사용하려면 Backstage를 사용해야 해요.

아직 Backstage를 설정하지 않았다면 여기에서 시작하세요.

TechDocs 프론트엔드 플러그인 추가하기

첫 번째 단계는 Backstage 애플리케이션에 TechDocs 플러그인을 추가하는 것이에요. 새 Backstage 애플리케이션 디렉터리로 이동한 뒤 packages/app 디렉터리로 이동해 @backstage/plugin-techdocs 패키지를 설치하세요.

Backstage 루트 디렉터리에서

yarn --cwd packages/app add @backstage/plugin-techdocs

패키지가 설치되면 앱에서 플러그인을 import해야 해요.

packages/app/src/App.tsx에서 TechDocsPage를 import하고 FlatRoutes에 다음을 추가하세요.

packages/app/src/App.tsx

import {  DefaultTechDocsHome,  TechDocsIndexPage,  TechDocsReaderPage,} from '@backstage/plugin-techdocs';const AppRoutes = () => {  <FlatRoutes>    {/* ... other plugin routes */}    <Route path="/docs" element={<TechDocsIndexPage />}>      <DefaultTechDocsHome />    </Route>    <Route      path="/docs/:namespace/:kind/:name/*"      element={<TechDocsReaderPage />}    />  </FlatRoutes>;};

페이지를 다른 것으로 꾸미는 것도 멋질 거예요... 문서에서 텍스트를 강조 표시할 때 새 이슈 페이지로 리다이렉트해 주는 링크가 있으면 정말 멋지겠죠? TechDocs Addon Framework를 사용해 이 작업을 하는 방법을 배워 보겠어요!

TechDocs Addon 프레임워크를 사용하면 문서 페이지에서 React 컴포넌트를 렌더링할 수 있으며 이런 Addon은 어떤 Backstage 플러그인이든 제공할 수 있어요. 이 프레임워크는 @backstage/plugin-techdocs-react 패키지에서 export되며, 이 두 의존성을 설치하고 나면 @backstage/plugin-techdocs-module-addons-contrib 패키지에 사용할 <ReportIssue /> Addon이 있어요.

import {  DefaultTechDocsHome,  TechDocsIndexPage,  TechDocsReaderPage,} from '@backstage/plugin-techdocs';import { TechDocsAddons } from '@backstage/plugin-techdocs-react';import { ReportIssue } from '@backstage/plugin-techdocs-module-addons-contrib';const AppRoutes = () => {  <FlatRoutes>    {/* ... other plugin routes */}    <Route path="/docs" element={<TechDocsIndexPage />}>      <DefaultTechDocsHome />    </Route>    <Route      path="/docs/:namespace/:kind/:name/*"      element={<TechDocsReaderPage />}    >      <TechDocsAddons>        <ReportIssue />      </TechDocsAddons>    </Route>  </FlatRoutes>;};

이게 어떻게 보이는지 궁금하시죠? 아래 이미지를 보세요.

"open new issue" 버튼을 클릭하면 사용 중인 소스 코드 제공자에 따라 새 이슈 페이지로 리다이렉트돼요.

이게 전부예요! 이제 프론트엔드가 작동하려면 TechDocs 백엔드 플러그인이 필요해요.

TechDocs 백엔드 플러그인 추가하기

먼저 @backstage/plugin-techdocs-backend 패키지를 설치해야 해요.

Backstage 루트 디렉터리에서

yarn --cwd packages/backend add @backstage/plugin-techdocs-backend

그런 다음 백엔드 index.ts에 다음 줄을 추가해요.

packages/backend/src/index.ts

const backend = createBackend();// Other plugins...backend.add(import('@backstage/plugin-techdocs-backend'));backend.start();

이게 전부예요! TechDocs 프론트엔드와 백엔드가 이제 Backstage 앱에 추가됐어요. 이제 필요에 맞게 몇 가지 설정을 조정해 보겠어요.

설정하기 (Setting the configuration)

완전한 구성 참조는 TechDocs 설정 옵션 문서를 참고하세요.

TechDocs 백엔드가 문서를 생성해야 하나요?

techdocs:  builder: 'local'

문서는 CI/CD에서 생성할 것을 권장한다는 점에 유의하세요. TechDocs 아키텍처의 "Basic"과 "Recommended" 섹션에서 자세히 읽어 보세요. 하지만 빠르게 시작하고 싶다면 techdocs.builder를 'local'로 설정해 TechDocs 백엔드가 문서 사이트 생성을 담당하게 하세요. 'external'로 설정하면 Backstage가 사이트가 각 엔터티의 CI/CD 파이프라인에서 생성되어 어딘가의 스토리지에 저장되고 있다고 가정해요.

techdocs.builder가 'external'로 설정되면, TechDocs는 생성된 모든 문서를 담은 스토리지에서 정적 파일을 서빙하는 읽기 전용 경험이 거의 돼요.

스토리지 선택(게시자)

TechDocs는 생성된 문서 사이트를 어디에 저장하고 어디에서 가져올지 알아야 해요. 이는 Publisher가 관리해요. 예: Google Cloud Storage, Amazon S3, 또는 Backstage 서버의 로컬 파일시스템.

처음으로 Backstage를 시험해 볼 때 "basic" 설정에서 로컬 파일시스템을 사용해도 괜찮아요. 나중에는 클라우드 스토리지 사용 문서를 검토하세요.

techdocs:  builder: 'local'  publisher:    type: 'local'

Docker in Docker 상황 비활성화(선택)

techdocs.builder가 'external'로 설정되어 있다면 이 단계를 건너뛰어도 돼요.

TechDocs 백엔드 플러그인은 mkdocs가 설치된 도커 컨테이너를 실행해 소스 파일(Markdown)에서 문서의 프론트엔드를 생성해요. Docker를 사용해 Backstage를 배포한다면, Backstage Docker 컨테이너가 TechDocs 백엔드를 위해 또 다른 Docker 컨테이너를 실행하려고 시도한다는 뜻이에요.

이 문제를 피하기 위해 사용할 수 있는 설정이 있어요. app-config.yaml에 기술 생성기가 local mkdocs를 실행할지 아니면 docker에서 실행할지 알려주는 값을 설정할 수 있어요. 구성이 제공되지 않으면 기본값은 docker로 실행하는 거예요.

techdocs:  builder: 'local'  publisher:    type: 'local'  generator:    runIn: local

generator.runIn을 local로 설정하면 환경이 techdocs와 호환되는지 확인해야 해요.

pip에서 mkdocs와 mkdocs-techdocs-core 패키지를 설치해야 하며, 선택적으로 OS 패키지 관리자(예: apt)에서 graphviz와 plantuml도 설치해야 해요.

Dockerfile의 USER node 바로 위에 다음 줄을 포함해 설치할 수 있어요.

RUN apt-get update && \    apt-get install -y python3 python3-pip python3-venv && \    rm -rf /var/lib/apt/lists/*ENV VIRTUAL_ENV=/opt/venvRUN python3 -m venv $VIRTUAL_ENVENV PATH="$VIRTUAL_ENV/bin:$PATH"RUN pip3 install mkdocs-techdocs-core

버전 요구 사항은 바뀔 수 있으니 우리의 Dockerfile을 확인해 그에 맞춰야 한다는 점에 유의하세요.

Debian 기반 Docker 컨테이너에서는 Python 패키지를 OS 패키지 관리자로 설치하거나 가상 환경 안에 설치해야 해요(관련 PEP 참고). 대안으로 pipx를 사용해 Python 패키지를 격리된 환경에 설치할 수도 있어요.

위 Dockerfile 스니펫은 최신 mkdocs-techdoc-core 패키지를 설치해요. 버전 번호는 해당 체인지로그에서 찾을 수 있어요. 버전을 고정하고 싶다면 아래 예시를 사용하세요.

RUN pip3 install mkdocs-techdocs-core==1.2.3

참고: Python 버전 3.11 이상을 권장해요.

주의: mkdocs-techdocs-core 패키지는 다른 모든 Python 패키지 다음에 설치하세요. 일부 의존성의 올바른 버전을 확보하려면 순서가 중요해요.

추가 자료 (Additional reading)

문서 생성 및 게시
README로 돌아가기