TechDocs 시작하기

원문 보기 위키 갱신 2026.10.07

참고

이 문서는 새 Backstage 앱에서 기본이 되는 새 프론트엔드 시스템을 기준으로 작성됐어요. Backstage 앱이 여전히 이전 프론트엔드 시스템을 사용한다면, 이 가이드의 이전 프론트엔드 시스템 버전을 대신 읽어 주세요.

출처: 문서

본문

참고

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

TechDocs는 Backstage에서 플러그인으로 동작하므로 TechDocs를 사용하려면 Backstage를 사용해야 해요. 기본 @backstage/create-app@latest 템플릿으로 만든 새로 스캐폴딩된 Backstage 앱에서는 TechDocs가 설치되어 프론트엔드와 백엔드 양쪽에 기본으로 연결(wired)돼요.

이제 필요에 맞게 몇 가지 설정을 조정해 보겠어요.

설정하기 (Setting the configuration)

TechDocs의 구성은 세 가지 주요 설정에 기반해요.

builder - 문서가 TechDocs 백엔드를 사용해 로컬에서 생성되는지, 아니면 Backstage 밖에서 빌드·게시되어 표시용으로 구성된 게시자(publisher)에서 가져오는지 결정해요.
generator - 문서가 mkdocs를 실행하는 Docker 이미지로 생성되는지, 아니면 직접 설치한 로컬 mkdocs 사본으로 생성되는지 결정해요.
publisher - 생성된 문서가 로컬 서버나 Google Cloud Storage 버킷 같은 다른 위치에 어디에 저장될지 지정해요.

기본적으로 TechDocs는 app-config.yaml에서 다음과 같이 설정돼요.

techdocs:  builder: 'local' # Alternatives - 'external'  generator:    runIn: 'docker' # Alternatives - 'local'  publisher:    type: 'local' # Alternatives include 'googleGcs', 'awsS3', and other supported publishers. See configuration documentation for the full list.

이 기본 구성으로 빠르게 시작할 수 있어요. 컴포넌트 문서를 다음과 같이 처리해요.

builder = local - TechDocs 백엔드를 사용해 문서를 생성하고 스토리지에 게시한 뒤 생성된 문서를 보여줘요.
generator.runIn = docker - 내부에서 mkdocs를 실행하는 techdocs-container 도커 이미지를 띄워 문서를 처리해요. 도커 이미지는 TechDocs가 자동으로 가져와요.
publisher.type = local - 생성된 문서 파일을 기본적으로 @backstage/plugin-techdocs-backend/static/docs나 techdocs.publisher.local.publishDirectory로 구성된 경로에 로컬로 저장해요.

generator와 publisher 설정을 더 세밀하게 조정할 수 있어요. 완전한 구성 참조는 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-techdocs-core 패키지를 설치해요. 버전 번호는 해당 체인지로그에서 찾을 수 있어요. 버전을 고정하고 싶다면 아래 예시를 사용하세요.

RUN pip3 install mkdocs-techdocs-core==1.2.3

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

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

TechDocs 애드온 사용하기

TechDocs 애드온 프레임워크를 사용하면 문서 페이지에서 React 컴포넌트를 렌더링할 수 있어요. 설치 지침, 사용 가능한 애드온 모듈, 사용 예시는 전용 TechDocs 애드온 가이드를 참고하세요.

추가 자료 (Additional reading)

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