TechDocs CLI
Backstage에서 TechDocs 사이트를 관리하기 위한 유틸리티 커맨드라인 인터페이스예요.
출처: 문서
본문
Backstage에서 TechDocs 사이트를 관리하기 위한 유틸리티 커맨드라인 인터페이스예요.
https://backstage.io/docs/features/techdocs/
특징(Features)
-
Backstage 앱에서 TechDocs 사이트의 로컬 개발/미리보기를 지원해요.
-
CI/CD 워크플로우에서 문서 사이트의 생성과 게시를 지원해요.
techdocs-cli --help
Usage: techdocs-cli [options] [command]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
generate|build [options] Generate TechDocs documentation site using mkdocs.
publish [options] Publish generated TechDocs site to an external storage AWS S3,
Google GCS, etc.
serve:mkdocs [options] Serve a documentation project locally using mkdocs serve.
serve [options] Serve a documentation project locally in a Backstage app-like
environment
help [command] display help for command
설치(Installation)
techdocs-cli의 최신 버전을 실행하려면 항상 npx를 쓸 수 있어요.
npx @techdocs/cli [command]
npm으로 설치할 수도 있어요.
npm install -g @techdocs/cli
techdocs-cli [command]
사용법(Usage)
Backstage 같은 환경에서 TechDocs 사이트를 로컬로 미리보기
techdocs-cli serve
기본적으로 Docker와 techdocs-container를 사용해 모든 의존성이 설치되도록 해요. 다만 --no-docker 플래그로 Docker를 비활성화할 수 있어요.
serve 명령은 Docker 이미지를 새로 끌어오지 않고 로컬에서 사용 가능한 이미지를 계속 사용한다는 점을 알아두세요. 문서 파일 변경이 더 이상 감지되지 않는 등 서빙이 잘못 동작한다면 docker pull spotify/techdocs로 이미지를 갱신하세요.
이 명령은 두 개의 로컬 서버를 시작해요. 하나는 8000 포트의 MkDocs 미리보기 서버, 다른 하나는 3000 포트의 Backstage 앱 서버예요. Backstage 앱은 MkDocs 미리보기 서버를 프록시로 사용해 생성된 문서 파일과 에셋을 가져오는 커스텀 TechDocs API 구현을 가져요.
Backstage 인스턴스는 제공된 미리보기 앱과 모양이나 동작이 다를 수 있어요. 다른 앱으로 문서를 미리보려면 --preview-app-bundle-path에 사용할 앱 번들의 경로를 넘기세요. 보통 dist나 build 디렉터리예요.
참고: 커스텀 techdocs 도커 이미지를 쓸 때는 엔트리포인트도 ENTRYPOINT ["mkdocs"]로 하거나 --docker-entrypoint로 재정의하세요.
명령 참조:
Usage: techdocs-cli serve [options]
Serve a documentation project locally in a Backstage app-like environment
Options:
-i, --docker-image <DOCKER_IMAGE> The mkdocs docker container to use (default: "spotify/techdocs")
--docker-entrypoint <DOCKER_ENTRYPOINT> Override the image entrypoint
--docker-option <DOCKER_OPTION...> Extra options to pass to the docker run command, e.g. "--add-host=internal.host:192.168.11.12"
(can be added multiple times).
--no-docker Do not use Docker, use MkDocs executable in current user environment.
--mkdocs-parameter-clean Pass "--clean" parameter to mkdocs server running in containerized environment.
--mkdocs-parameter-dirtyreload Pass "--dirtyreload" parameter to mkdocs server running in containerized environment.
--mkdocs-parameter-strict Pass "--strict" parameter to mkdocs server running in containerized environment.
--mkdocs-port <PORT> Port for MkDocs server to use (default: "8000")
--preview-app-bundle-path <PATH_TO_BUNDLE> Preview documentation using a web app other than the included one.
--preview-app-port <PORT> Port where the preview will be served.
Can only be used with "--preview-app-bundle-path". (default: "3000")
-c, --mkdocs-config-file-name <FILENAME> Yaml file to use as config by mkdocs.
-v --verbose Enable verbose output. (default: false)
-h, --help display help for command
문서 프로젝트에서 TechDocs 사이트 생성하기
techdocs-cli generate
별칭: techdocs-cli build
generate 명령은 일관성을 위해 Backstage의 @backstage/plugin-techdocs-node 패키지를 사용해요. app-config.yaml에서 techdocs.builder를 'local'로 설정하면 Backstage 앱이 TechDocs 사이트를 생성하고 게시할 수도 있어요. 구성 참조를 보세요.
기본적으로 이 명령은 Docker와 techdocs-container를 사용해 모든 의존성이 설치되도록 해요. 하지만 --no-docker 플래그로 비활성화할 수 있어요.
명령 참조:
techdocs-cli generate --help
Usage: techdocs-cli generate|build [options]
Generate TechDocs documentation site using MkDocs.
Options:
--source-dir <PATH> Source directory containing mkdocs.yml and docs/ directory. (default: ".")
--output-dir <PATH> Output directory containing generated TechDocs site. (default: "./site/")
--docker-image <DOCKER_IMAGE> The mkdocs docker container to use (default: "spotify/techdocs:v1.0.3")
--no-pull Do not pull the latest docker image
--no-docker Do not use Docker, use MkDocs executable and plugins in current user environment.
--techdocs-ref <HOST_TYPE:URL> The repository hosting documentation source files e.g.
url:https://ghe.mycompany.net.com/org/repo.
This value is same as the backstage.io/techdocs-ref annotation of the corresponding
Backstage entity.
It is completely fine to skip this as it is only being used to set repo_url in mkdocs.yml
if not found.
--etag <ETAG> A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored
in techdocs_metadata.json. If omitted, a sha256 content hash of the generated site output is
computed automatically.
--defaultPlugin <PLUGIN_NAME> Plugins which should be added automatically to the mkdocs.yaml file. Also permits these
plugins through plugin validation. (default: [])
--omitTechdocsCoreMkdocsPlugin An option to disable automatic addition of techdocs-core plugin to the mkdocs.yaml files.
Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file.
--dangerouslyAllowAdditionalKeys [additionalKeys...]
Top-level mkdo...
생성된 TechDocs 사이트 게시하기
techdocs-cli publish --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --entity <namespace/kind/name>
techdocs-cli generate로 TechDocs 사이트를 생성한 뒤, publish 명령으로 생성된 정적 파일을 Backstage 앱이 읽을 수 있는 클라우드 저장(AWS/GCS) 버킷이나 (Azure) 컨테이너에 업로드해요.
--entity 값은 생성된 TechDocs 사이트가 속한 Backstage 엔티티여야 해요. 엔티티의 catalog-info.yaml 파일에서 값을 찾을 수 있어요. catalog-info.yaml에 namespace가 없으면 default를 사용하세요. 저장 버킷에 사용되는 디렉터리 구조는 namespace/kind/name/<files>예요.
값은 대소문자를 구분한다는 점을 알아두세요. --entity 예시는 default/Component/<entityName>이에요.
명령 참조:
Usage: techdocs-cli publish [options]
Publish generated TechDocs site to an external storage AWS S3, Google GCS, etc.
Options:
--publisher-type <TYPE> (Required always) awsS3 | googleGcs | azureBlobStorage | openStackSwift - same as techdocs.publisher.type in Backstage app-config.yaml
--storage-name <BUCKET/CONTAINER NAME> (Required always) In case of AWS/GCS, use the bucket name. In case of Azure, use container name. Same as
techdocs.publisher.[TYPE].bucketName
--entity <NAMESPACE/KIND/NAME> (Required always) Entity uid separated by / in namespace/kind/name order (case-sensitive). Example: default/Component/myEntity
--legacyUseCaseSensitiveTripletPaths Publishes objects with cased entity triplet prefix when set (e.g. namespace/Kind/name). Only use if your TechDocs backend is configured
the same way. (default: false)
--azureAccountName <AZURE ACCOUNT NAME> (Required for Azure) specify when --publisher-type azureBlobStorage
--azureAccountKey <AZURE ACCOUNT KEY> Azure Storage Account key to use for authentication. If not specified, you must set AZURE_TENANT_ID, AZURE_CLIENT_ID &
AZURE_CLIENT_SECRET as environment variables.
--awsRoleArn <AWS ROLE ARN> Optional AWS ARN of role to be assumed.
--awsEndpoint <AWS ENDPOINT> Optional AWS endpoint to send requests to.
--awsProxy <HTTPS Proxy> Optional Proxy to use for AWS requests.
--awsS3sse <AWS SSE> Optional AWS S3 Server Side Encryption.
--awsS3ForcePathStyle Optional AWS S3 option to ...
프록시 뒤에서 게시하기
HTTP_PROXY/HTTPS_PROXY/NO_PROXY와 함께 NODE_USE_ENV_PROXY=1을 설정해 TechDocs 게시를 프록시로 라우팅하세요. 자세한 내용은 기업 프록시 가이드를 참고해요.
대소문자 무관 접근을 위한 콘텐츠 마이그레이션
TechDocs 베타 버전(v[0.11.0]) 이전에는 TechDocs가 대소문자 구분 엔티티 트리플릿(예: default/API/name/index.html)으로 객체 저장에 저장됐어요. 이로 인해 Backstage URL에서 정확히 같은 대소문자를 요구해야 TechDocs 콘텐츠를 읽거나 렌더링할 수 있는 제약이 생겼어요. TechDocs 플러그인 v[0.11.0]부터는 URL에서 어떤 대소문자든 허용돼요(예: default/api/name). 이는 Catalog 플러그인의 동작과 일치해요.
TechDocs v[0.11.0] 이상으로 생성된 Backstage 인스턴스는 이 명령이 필요 없어요. 하지만 이 버전으로 이전 버전에서 업그레이드할 때, 모든 문서를 다시 빌드하지 않고도 문서에 계속 접근할 수 있도록 배포 전에 migrate 명령을 사용할 수 있어요.
v[0.11.0] 이상으로 업그레이드하기 전에 이 명령을 실행해 모든 에셋을 소문자 트리플릿에 해당하는 것으로 복사하세요.
techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --verbose
마이그레이션하고 업그레이드된 Backstage 플러그인 버전을 배포한 뒤에는 --removeOriginal 플래그를 붙여 명령을 다시 실행하면 레거시(대소문자 구분) 트리플릿 파일을 정리할 수 있어요. 이 플래그는 파일을 복사가 아니라 이동시켜요. 참고: 이는 파일을 삭제하므로 주의해서 수행해야 하는 파괴적 연산이에요.
techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --removeOriginal --verbose
그 후 TechDocs CLI를 v[0.7.0]으로 업데이트해 이후 게시가 소문자 엔티티 트리플릿으로 이뤄지도록 하세요.
참고: 이 명령의 인자는 선택한 저장 제공자에 따라 대부분 publish 명령과 일치해요. 자세한 내용은 techdocs-cli migrate --help를 실행하세요.
인증(Authentication)
환경이 대상 클라우드 제공자와 인증할 수 있는지 확인해야 해요. techdocs-cli는 AWS(v3), Google Cloud, Azure가 제공하는 공식 Node.js 클라이언트를 사용해요. 환경 변수 및/또는 다른 수단(~/.aws/credentials, ~/.config/gcloud 등)으로 인증할 수 있어요.
클라우드 저장 제공자에 따라 다음 문서의 인증 섹션을 참고하세요.
-
Google Cloud Storage
-
AWS S3
-
Azure Blob Storage
개발(Development)
TechDocs CLI를 개선하고 새 기능을 지원하는 데 기여해 주세요! 자세한 내용은 프로젝트 README를 참고하세요.