001 - 스캐폴딩

원문 보기 위키 갱신 2026.10.07

이 가이드는 여러분만의 커스터마이징 가능한 Backstage 앱을 만드는 방법을 시작부터 안내해요. 이것은 Backstage를 평가·개발·데모하는 첫 단계예요. 이 가이드가 끝나면 SQLite 데이터베이스와 데모 콘텐츠가 포함된 독립 실행형 Backstage 설치가 로컬에서 실행될 거예요.

출처: 문서

본문

대상 독자: 개발자 및 관리자

이 가이드를 시작하기 전에 Yarn과 npm에 대한 기본적인 이해가 있으면 필수는 아니지만 권장돼요.

요약

이 가이드는 여러분만의 커스터마이징 가능한 Backstage 앱을 만드는 방법을 시작부터 안내해요. 이것은 Backstage를 평가·개발·데모하는 첫 단계예요.

이 가이드가 끝나면 SQLite 데이터베이스와 데모 콘텐츠가 포함된 독립 실행형 Backstage 설치를 로컬에서 실행하게 될 거예요.

조직 커스터마이징

분명히 말하지만, 이것은 프로덕션 준비가 된 설치가 아니고 조직 특유의 정보도 포함하지 않아요. 이 가이드를 통해 사용 사례에 맞게 Backstage를 커스터마이징하는 방법을 배우게 될 거예요.

사전 준비 사항

이 가이드는 Linux 기반 운영체제에서 작업하는 기본적인 이해와 터미널 사용 경험, 특히 npm, yarn 명령에 대한 경험을 가정해요.

Linux, macOS 또는 WSL(Windows Subsystem for Linux) 같은 Unix 기반 운영체제에 대한 접근
명령줄에서 사용 가능한 GNU 계열 빌드 환경. 예를 들어 Debian/Ubuntu에서는 make와 build-essential 패키지를 설치해야 해요. macOS에서는 XCode 명령줄 빌드 도구를 갖추기 위해 xcode-select --install을 실행해야 해요.
의존성을 설치할 수 있는 상위 권한을 가진 계정
curl 또는 wget 설치
다음 방법 중 하나로 설치된 Node.js Active LTS 릴리스:
nvm 사용 (권장)
nvm 설치
nvm으로 Node 버전 설치 및 변경
Node 20이 좋은 출발점이며, nvm install lts/iron으로 설치할 수 있어요.
바이너리 다운로드
패키지 매니저
NodeSource 패키지 사용
yarn 설치
Backstage는 현재 Yarn 4.4.1을 사용하며, corepack enable을 실행한 후 yarn set version 4.4.1을 실행해야 해요.
git 설치

새 Backstage 앱 스캐폴드하기

1. Backstage 앱 만들기

새 Backstage 앱을 스캐폴드하기 위해 대화형 명령을 실행할 거예요. 명령을 실행하기 전에 터미널을 열고 현재 작업 디렉터리를 새 디렉터리를 만들어도 편한 곳으로 이동해야 해요.

이 명령의 마법사는 새 앱에 사용할 이름을 물어봐요. 그 이름이 우리가 만들어 줄 폴더와 일치해요.

명령을 실행하면 다음과 같은 출력이 보일 거예요.

? Enter a name for the app [required] my-backstage-appCreating the app...Checking if the directory is available:checking      my-backstage-app ✔Creating a temporary app directory:Preparing files:copying       .dockerignore ✔copying       .eslintignore ✔templating    .eslintrc.js.hbs ✔...Moving to final location:moving        my-backstage-app ✔fetching      yarn.lock seed ✔Installing dependencies:executing     yarn install ✔executing     yarn tsc ✔Successfully created my-backstage-app

그리고 끝나면 (예시 데이터가 포함된) 동작하는 Backstage 앱이 생겼을 거예요!

이제 그것이 무엇을 하는지 알았으니, 실제로 코드를 스캐폴드해 볼까요!

npx @backstage/create-app@latest

모든 것을 완전히 설치하는 데 몇 분이 걸릴 수 있어요. 로딩이 끝없이 도는 것처럼 보여도 스트레스 받지 마세요. 백그라운드에서 많은 일이 일어나고 있어요.

앱의 구조

일반적인 폴더 구조

다음은 앱을 만들 때 생성되는 파일과 폴더의 단순화된 레이아웃이에요.

app├── app-config.yaml├── catalog-info.yaml├── package.json└── packages    ├── app    └── backend

app-config.yaml: 앱의 메인 구성 파일. 자세한 내용은 구성을 참고하세요.
catalog-info.yaml: 카탈로그 엔티티 디스크립터. 시작하려면 카탈로그 엔티티의 디스크립터 형식을 참고하세요.
package.json: 프로젝트의 루트 package.json. 참고: npm 의존성을 여기에 추가하지 않도록 주의하세요. 의도된 워크스페이스에 설치되어야 하지, 루트에 설치되어서는 안 되기 때문이에요.
packages/: Lerna 리프 패키지 또는 "워크스페이스". 여기의 모든 것은 lerna로 관리되는 별도의 패키지예요.
packages/app/: Backstage를 알아가는 좋은 출발점이 되는 완전히 기능하는 Backstage 프론트엔드 앱.
packages/backend/: 무엇보다도 인증, 소프트웨어 카탈로그, 소프트웨어 템플릿, TechDocs 같은 기능을 지원하는 데 도움이 되는 백엔드를 포함해요.

일반적인 문제

앱이 X 포트에서 실행되지 않음: Backstage는 기본 프론트엔드 및 백엔드 포트로 3000과 7007을 사용해요. 명령이 오류로 종료되지 않았는지 확인하세요. 원격 또는 컨테이너화된 설정에서는 위 포트에 접근할 수 있는지 확인하세요.

다음 단계

이제 스캐폴드된 앱이 있으니, 개발을 위해 로컬에서 시작하는 방법을 배워 볼게요!