TechDocs 설정 옵션
Backstage 앱의 app-config.yaml을 사용하면 여러 옵션으로 TechDocs를 설정할 수 있어요. 이 페이지는 TechDocs에서 사용할 수 있는 모든 설정 옵션에 대한 참조 자료 역할을 해요.
출처: 문서
본문
Backstage 앱의 app-config.yaml을 사용하면 여러 옵션으로 TechDocs를 설정할 수 있어요. 이 페이지는 TechDocs에서 사용할 수 있는 모든 설정 옵션에 대한 참조 자료 역할을 해요.
생성기 설정 (Generator Configuration)
techdocs.generator는 MkDocs를 사용해 문서 사이트를 어떻게 생성할지 설정하는 데 사용돼요.
실행 방식 (Run In)
techdocs.generator.runIn
옵션: 'docker' 또는 'local'
이 값은 생성기를 어떻게 실행할지 결정해요. techdocs-container 도커 이미지를 띄울지, 아니면 (모든 의존성이 준비되어 있다고 가정하고) 로컬에서 mkdocs를 실행할지 정해요.
자체 커스텀 Docker 설정으로 Backstage를 실행 중이고 Docker in Docker 상황을 피하고 싶다면 이 값을 'local'로 바꾸면 돼요. 자세한 내용은 여기를 읽어 보세요.
예시:
techdocs: generator: runIn: 'docker'
Docker 이미지
techdocs.generator.dockerImage
(선택) 문서 생성 중 사용할 도커 이미지를 제어하는 데 사용할 수 있어요. 기본 techdocs-container(spotify/techdocs)에 포함되지 않은 MkDocs 플러그인이나 다른 패키지를 사용하고 싶을 때 유용해요.
참고: 이 설정은 techdocs.generator.runIn이 'docker'로 설정되어 있을 때만 사용돼요.
예시:
techdocs: generator: runIn: 'docker' dockerImage: 'spotify/techdocs'
이미지 가져오기 (Pull Image)
techdocs.generator.pullImage
(선택) 기본적으로 최신 도커 이미지를 가져오는 동작을 비활성화하는 데 사용할 수 있어요. 커스텀 techdocs.generator.dockerImage를 사용하면서 커스텀 docker 로그인 요구 사항이 있을 때 유용해요. 예를 들어 도커 이미지를 가져오려면 AWS ECR에 로그인해야 하는 경우가 있어요.
참고: 이 기능을 비활성화하려면 techdocs 생성기를 실행하기 전에 다른 방법으로 도커 이미지를 가져와야 해요.
예시:
techdocs: generator: runIn: 'docker' dockerImage: 'custom-registry/techdocs' pullImage: false
가져오기 옵션 (Pull Options)
techdocs.generator.pullOptions
(선택) 도커 이미지를 가져올 때 인증 옵션을 전달하는 데 사용할 수 있어요. techdocs.generator.dockerImage가 설정되고 techdocs.generator.pullImage가 true(또는 설정되지 않아 기본 가져오기 동작을 사용하는 경우)이며 이미지가 프라이빗 레지스트리에 호스팅되어 있을 때 유용해요.
authconfig를 설정해 레지스트리 자격 증명을 제공할 수 있어요. 지원되는 필드와 더 많은 예시는 프라이빗 저장소에서 가져오기에 관한 Dockerode 문서를 참고해 주세요.
예시:
techdocs: generator: runIn: 'docker' dockerImage: 'custom-registry/techdocs' pullImage: true pullOptions: authconfig: username: ${REGISTRY_USERNAME} password: ${REGISTRY_PASSWORD} serveraddress: 'https://index.docker.io/v1'
MkDocs 설정
TechDocs Core 플러그인 생략
techdocs.generator.mkdocs.omitTechdocsCorePlugin
(선택) mkdocs.yaml 파일에 techdocs-core 플러그인을 자동으로 추가하는 기능을 비활성화하는 데 사용할 수 있어요. 기본값은 false이며, 이는 techdocs-core 플러그인이 항상 mkdocs 파일에 추가된다는 뜻이에요.
예시:
techdocs: generator: mkdocs: omitTechdocsCorePlugin: false
레거시 README를 index로 복사
techdocs.generator.mkdocs.legacyCopyReadmeMdToIndexMd
(선택이며 권장하지 않음) 기본 <docs-dir>/index.md가 제공되지 않을 때 <docs-dir>/README.md 또는 README.md를 대체로 사용해 index.md가 존재하도록 techdocs 생성기를 설정해요.
참고: https://www.mkdocs.org/user-guide/configuration/#edit_uri 동작은 이러한 시나리오에서 깨질 수 있어요.
예시:
techdocs: generator: mkdocs: legacyCopyReadmeMdToIndexMd: false
외부 폰트 비활성화
techdocs.generator.mkdocs.disableExternalFonts
(선택) 생성기가 인터넷에 연결할 수 없을 때(예: air-gapped 또는 제한된 네트워크) 사용해요. 그렇지 않으면 MkDocs Material이 생성 중에 Google에서 Roboto 폰트를 다운로드하려고 해요.
true로 설정하면 TechDocs가 생성 중에 각 mkdocs.yml을 패치해요. theme 섹션이 없으면 name: material과 font: false를 추가하고, theme는 있지만 font가 없으면 font: false를 설정하며, 파일에 font가 이미 설정되어 있으면 값을 그대로 둬요.
예시:
techdocs: generator: mkdocs: disableExternalFonts: true
또는 mkdocs.yml을 수동으로 설정할 수도 있어요:
theme: name: material font: false
참고: mkdocs.yml에서 theme.font를 사용할 때는 theme.name: material이 필요해요. 파일에 font가 이미 설정되어 있으면 app-config 패치가 이를 덮어쓰지 않아요. font가 설정되어 있지 않을 때만 font: false를 추가해요.
기본 플러그인 (Default Plugins)
techdocs.generator.mkdocs.defaultPlugins
(선택) 모든 mkdocs.yaml 파일에 자동으로 추가되어야 하는 기본 플러그인을 설정해요. 예를 들어 스타일링 플러그인을 한 번만 추가해 모두에 적용할 수 있어 사용이 간편해져요.
정의한 플러그인이 로컬이나 Docker 이미지에 설치되어 있는지 확인해야 해요. 기본적으로 techdocs-core 플러그인만 추가돼요(omitTechdocsCorePlugin: true가 아닌 경우).
예시:
techdocs: generator: mkdocs: defaultPlugins: ['techdocs-core']
추가 키 위험 허용 (Dangerously Allow Additional Keys)
techdocs.generator.mkdocs.dangerouslyAllowAdditionalKeys
(선택) 기본적으로 TechDocs는 mkdocs.yml을 지원하는 최상위 키의 내장 허용 목록에 대해 검증해요. 이 옵션은 일부 MkDocs 플러그인이 요구하는 hooks 키 같은 추가 키를 실패시키거나 제거하지 않고 명시적으로 허용해요. 주의해서 사용해야 해요. 허용된 키는 검증 없이 그대로 전달돼요.
예시:
techdocs: generator: mkdocs: dangerouslyAllowAdditionalKeys: ['hooks']
techdocs-cli generate를 직접 실행할 때는 CLI가 현재 설정 파일에서 이 옵션을 읽지 않으므로 --dangerouslyAllowAdditionalKeys CLI 플래그로 동일한 동작을 사용할 수 있어요.
허용된 MkDocs 플러그인 (Permitted MkDocs Plugins)
TechDocs는 문서 생성 중에 mkdocs.yml의 MkDocs 플러그인 선언을 검증해요. 기본적으로 techdocs-core, search, material/search, redirects, group, material/group을 허용해요. 다른 플러그인은 빌드가 실행되기 전에 제거되고 경고가 기록돼요.
문서에 다른 플러그인이 필요하다면 dangerouslyAllowAdditionalPlugins를 사용해 허용 집합을 확장할 수 있어요. 문서 작성자가 제공할 수 있는 모든 설정 옵션을 포함해 사용 환경에서 감사(audit)를 거친 플러그인만 허용해야 해요. MkDocs 플러그인은 문서 생성의 일부로 실행되며, 예를 들어 외부 요청을 보내거나 코드를 실행할 수 있어요.
예시:
techdocs: generator: mkdocs: dangerouslyAllowAdditionalPlugins: - my-custom-plugin - another-plugin
defaultPlugins에 나열된 플러그인도 자동으로 허용되며 동일한 신뢰 고려 사항이 적용돼요. TechDocs CLI를 사용할 때는 --defaultPlugin을 사용해 플러그인을 추가하거나 허용할 수 있어요.
빌더 설정 (Builder Configuration)
techdocs.builder
옵션: 'local' 또는 'external'
기본 빌드 전략을 사용할 때:
-
빌더가
'local'로 설정되고 TechDocs 페이지를 열면, techdocs-backend가 문서를 생성하려고 시도하고 스토리지에 게시한 뒤 생성된 문서를 보여줘요. 이것이 TechDocs 아키텍처의 "Basic" 설정이에요. -
빌더가
'external'('local'이외의 값)로 설정되면, techdocs-backend는 문서를 가져오기만 하고 생성·게시하려고 시도하지 않아요. 이 경우 문서가 외부 프로세스(예: 저장소의 CI/CD 파이프라인)에 의해 빌드된다고 가정해요. 이것이 아키텍처의 "Recommended" 설정이에요.
참고: 커스텀 빌드 전략이 이 동작을 바꿀 수 있어요.
"Basic"과 "Recommended" 설정에 대해 자세히 읽어 보세요.
빌드 전략에 대해 자세히 읽어 보세요.
예시:
techdocs: builder: 'local'
게시자 설정 (Publisher Configuration)
techdocs.publisher
이 값은 스토리지 옵션을 설정하는 데 사용돼요. 생성된 문서를 로컬 파일시스템에 저장할지, 아니면 Google Cloud Storage, AWS S3 같은 외부 스토리지 제공자를 사용할지 정해요.
게시자 유형 (Publisher Type)
techdocs.publisher.type
이 값은 생성된 문서 파일을 어디에 저장할지 결정해요.
옵션:
-
'local'- techdocs-backend가 루트에 'static' 디렉터리를 만들어 생성된 문서 파일을 저장해요 -
'googleGcs'- techdocs-backend가 Google Cloud Storage 버킷을 사용해요 -
'awsS3'- techdocs-backend가 AWS S3 버킷을 사용해요 -
'azureBlobStorage'- techdocs-backend가 Azure Blob Storage를 사용해요
예시:
techdocs: publisher: type: 'local'
로컬 스토리지 (Local Storage)
techdocs.publisher.local
이 값은 로컬 스토리지 옵션을 설정하는 데 사용돼요.
techdocs.publisher.type이 'local'로 설정된 경우 선택 사항이에요.
게시 디렉터리 (Publish Directory)
techdocs.publisher.local.publishDirectory
(선택) 생성된 문서를 어디에 저장할지 지정해요.
예시:
techdocs: publisher: type: 'local' local: publishDirectory: '/path/to/local/directory'
Google Cloud Storage
techdocs.publisher.googleGcs
이 값은 Google Cloud Storage 옵션을 설정하는 데 사용돼요.
techdocs.publisher.type이 'googleGcs'로 설정된 경우 필수예요. 그 외에는 건너뛰세요.
버킷 이름 (Bucket Name)
techdocs.publisher.googleGcs.bucketName
(필수) Cloud Storage 버킷 이름
예시:
techdocs: publisher: type: 'googleGcs' googleGcs: bucketName: 'techdocs-storage'
버킷 루트 경로 (Bucket Root Path)
techdocs.publisher.googleGcs.bucketRootPath
(선택) 저장소 버킷에서 파일을 저장할 위치예요. 설정하지 않으면 기본 위치는 저장소 버킷의 루트가 돼요.
예시:
techdocs: publisher: type: 'googleGcs' googleGcs: bucketName: 'techdocs-storage' bucketRootPath: '/docs'
자격 증명 (Credentials)
techdocs.publisher.googleGcs.credentials
(선택) 저장소 버킷에 쓰는 데 필요한 API 키예요. 없으면 GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 사용해요. https://cloud.google.com/docs/authentication/production
예시:
techdocs: publisher: type: 'googleGcs' googleGcs: bucketName: 'techdocs-storage' credentials: $file: '/path/to/google_application_credentials.json'
AWS S3
techdocs.publisher.awsS3
이 값은 AWS S3 옵션을 설정하는 데 사용돼요.
techdocs.publisher.type이 'awsS3'로 설정된 경우 필수예요. 그 외에는 건너뛰세요.
버킷 이름 (Bucket Name)
techdocs.publisher.awsS3.bucketName
(필수) AWS S3 버킷 이름
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage'
버킷 루트 경로 (Bucket Root Path)
techdocs.publisher.awsS3.bucketRootPath
(선택) 저장소 버킷에서 파일을 저장할 위치예요. 설정하지 않으면 기본 위치는 저장소 버킷의 루트가 돼요.
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage' bucketRootPath: '/documentation'
계정 ID (Account ID)
techdocs.publisher.awsS3.accountId
스토리지 버킷이 있는 AWS 계정 ID예요. 계정 ID의 자격 증명은 aws 앱 구성 섹션에 설정되어 있어야 해요. aws 앱 구성 섹션에서 자격 증명을 설정하는 방법에 대한 자세한 내용은 integration-aws-node 패키지를 참고해 주세요.
계정 ID가 설정되어 있지 않고 자격 증명도 없으면 인증에 환경 변수나 AWS 구성 파일이 사용돼요.
https://www.npmjs.com/package/@aws-sdk/credential-provider-node https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage' accountId: ${TECHDOCS_AWSS3_ACCOUNT_ID}
자격 증명 (Credentials)
techdocs.publisher.awsS3.credentials
(선택) 스토리지 버킷에 쓰는 데 사용할 AWS 자격 증명이에요. 이 구성 섹션은 이제 폐기(deprecated)되었어요. 이제는 aws 앱 구성 섹션의 자격 증명과 함께 계정 ID를 구성하는 것이 권장돼요.
자격 증명이 설정되어 있지 않고 계정 ID도 없으면 인증에 환경 변수나 AWS 구성 파일이 사용돼요.
https://www.npmjs.com/package/@aws-sdk/credential-provider-node https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage' credentials: accessKeyId: ${TECHDOCS_AWSS3_ACCESS_KEY_ID_CREDENTIAL} secretAccessKey: ${TECHDOCS_AWSS3_SECRET_ACCESS_KEY_CREDENTIAL}
리전 (Region)
techdocs.publisher.awsS3.region
(선택) 버킷의 AWS 리전이에요. 설정하지 않으면 AWS_REGION 환경 변수나 AWS 구성 파일이 사용돼요.
https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage' region: ${AWS_REGION}
엔드포인트 (Endpoint)
techdocs.publisher.awsS3.endpoint
(선택) 요청을 보낼 엔드포인트 URI예요. 설정하지 않으면 구성된 리전에서 기본 엔드포인트가 만들어져요.
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage' endpoint: ${AWS_ENDPOINT}
HTTPS 프록시
techdocs.publisher.awsS3.httpsProxy
(선택) S3 요청에 사용할 HTTPS 프록시예요. 기본값은 프록시를 사용하지 않는 것이에요. 이 덕분에 프록시 뒤에서 문서를 게시하고 읽을 수 있어요.
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage' httpsProxy: ${HTTPS_PROXY}
S3 Force Path Style
techdocs.publisher.awsS3.s3ForcePathStyle
(선택) S3와 통신할 때 path style URL을 사용할지 여부예요. 기본값은 false예요. 이 덕분에 LocalStack, Minio, Wasabi 같은 제공자를 사용해 tech docs를 호스팅할 수 있어요.
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage' s3ForcePathStyle: true
서버 측 암호화 (Server Side Encryption)
techdocs.publisher.awsS3.sse
(선택) AWS 서버 측 암호화예요. 기본값은 undefined예요. 설정하지 않으면 암호화된 버킷에 게시하지 못해요.
https://docs.aws.amazon.com/AmazonS3/latest/userguide/specifying-s3-encryption.html
옵션: 'aws:kms' 또는 'AES256'
예시:
techdocs: publisher: type: 'awsS3' awsS3: bucketName: 'techdocs-storage' sse: 'aws:kms'
Azure Blob Storage
techdocs.publisher.azureBlobStorage
techdocs.publisher.type이 'azureBlobStorage'로 설정된 경우 필수예요. 그 외에는 건너뛰세요.
컨테이너 이름 (Container Name)
techdocs.publisher.azureBlobStorage.containerName
(필수) Azure Blob Storage 컨테이너 이름
예시:
techdocs: publisher: type: 'azureBlobStorage' azureBlobStorage: containerName: 'techdocs-storage'
연결 문자열 (Connection String)
techdocs.publisher.azureBlobStorage.connectionString
(선택) Azure blob storage 연결 문자열이에요. azurite로 로컬 테스트할 때 유용할 수 있어요. 기본값은 undefined예요. 제공되면 우선순위가 더 높아지고 techdocs.publisher.azureBlobStorage.credentials는 무시돼요.
예시:
techdocs: publisher: type: 'azureBlobStorage' azureBlobStorage: containerName: 'techdocs-storage' connectionString: 'DefaultEndpointsProtocol=https;AccountName=...'
자격 증명 (Credentials)
techdocs.publisher.azureBlobStorage.credentials
(필수) 스토리지 blob 컨테이너에 쓰기 위한 계정 이름이에요.
https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key
(선택) 스토리지 컨테이너에 쓰려면 계정 키가 필요해요. 없으면 AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET 환경 변수가 사용돼요.
https://docs.microsoft.com/en-us/azure/storage/common/storage-auth?toc=/azure/storage/blobs/toc.json
예시:
techdocs: publisher: type: 'azureBlobStorage' azureBlobStorage: containerName: 'techdocs-storage' credentials: accountName: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME} accountKey: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY}
레거시 대소문자 구분 트리플릿 경로
techdocs.legacyUseCaseSensitiveTripletPaths
(선택이며 권장하지 않음) TechDocs의 [0.x.y] 버전 이전에는 문서 사이트가 대소문자를 구분하는 엔터티 트리플릿(예: namespace/Kind/name) 경로로만 접근할 수 있었어요. 이전 버전의 TechDocs에서 업그레이드 중이고 외부 스토리지의 파일을 필요한 마이그레이션으로 처리할 수 없다면, 이 값을 true로 설정해 일시적으로 이전의 대소문자 구분 엔터티 트리플릿 동작으로 되돌릴 수 있어요.
예시:
techdocs: legacyUseCaseSensitiveTripletPaths: false
캐시 설정 (Cache Configuration)
techdocs.cache
(선택) techdocs.cache는 위에서 외부 techdocs.publisher.type을 구성한 경우에만 권장돼요. 또한 backend.cache에 유효한 캐시 저장소가 구성되어 있어야 해요. techdocs.cache.ttl을 설정해 techdocs 자산 캐싱을 활성화할 수 있어요.
TTL
techdocs.cache.ttl
정적으로 빌드된 자산이 캐시에 유지되어야 하는 밀리초 수를 나타내요. 캐시 무효화는 프론트엔드가 캐시된 메타데이터의 빌드 시간과 정식 스토리지를 비교해 자동으로 처리하므로 긴 TTL(예: 1개월/1년)을 사용할 수 있어요.
예시:
techdocs: cache: ttl: 3600000
읽기 타임아웃 (Read Timeout)
techdocs.cache.readTimeout
(선택) TechDocs 백엔드가 캐시 서비스의 응답을 기다리는 시간(밀리초)이에요. 이 시간이 지나면 캐시된 객체를 찾지 못한 것처럼 계속 진행해요(예: 캐시 서비스를 사용할 수 없을 때). 기본값은 1000이에요.
예시:
techdocs: cache: ttl: 3600000 readTimeout: 500