3장: Backstage로 개발자 포털 구축

# Node.js 20 이상
node --version
# v20.x.x
 
# Yarn (Backstage는 Yarn을 기본 패키지 관리자로 사용)
yarn --version
# 4.x.x
 
# Docker (선택사항, PostgreSQL 실행용)
docker --version

# Backstage CLI로 새 앱 생성
npx @backstage/create-app@latest
 
# 앱 이름 입력
# ? Enter a name for the app: my-company-portal
 
# 생성된 디렉토리로 이동
cd my-company-portal
 
# 개발 서버 실행
yarn dev

app:
  title: "My Company Developer Portal"
  baseUrl: http://localhost:3000
 
organization:
  name: "My Company"
 
backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  database:
    client: pg
    connection:
      host: localhost
      port: 5432
      user: backstage
      password: ${POSTGRES_PASSWORD}
 
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}
 
auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}
 
catalog:
  import:
    entityFilename: catalog-info.yaml
    pullRequestBranchName: backstage-integration
  rules:
    - allow: [Component, System, API, Resource, Location, Domain, Group, User]
  locations:
    - type: file
      target: ../../examples/entities.yaml
    - type: file
      target: ../../examples/template/template.yaml
      rules:
        - allow: [Template]

app:
  baseUrl: https://backstage.mycompany.com
 
backend:
  baseUrl: https://backstage-api.mycompany.com
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: 5432
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
    plugin:
      catalog:
        connection:
          database: backstage_plugin_catalog
      auth:
        connection:
          database: backstage_plugin_auth
 
auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${GITHUB_CLIENT_ID}
        clientSecret: ${GITHUB_CLIENT_SECRET}

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: "사용자 인증 및 프로필 관리 서비스"
  annotations:
    github.com/project-slug: mycompany/user-service
    backstage.io/techdocs-ref: dir:.
  tags:
    - java
    - spring-boot
    - grpc
  links:
    - url: https://grafana.mycompany.com/d/user-service
      title: Grafana Dashboard
      icon: dashboard
spec:
  type: service
  lifecycle: production
  owner: team-auth
  system: user-management
  dependsOn:
    - resource:default/user-database
    - component:default/notification-service
  providesApis:
    - user-api

site_name: User Service
site_description: "사용자 인증 및 프로필 관리 서비스 문서"
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api-reference.md
  - Runbook: runbook.md
  - ADR:
    - "ADR-001: 인증 방식 선택": adr/001-auth-method.md
    - "ADR-002: 데이터베이스 선택": adr/002-database-choice.md
 
plugins:
  - techdocs-core

user-service/
  catalog-info.yaml
  mkdocs.yml
  docs/
    index.md
    architecture.md
    api-reference.md
    runbook.md
    adr/
      001-auth-method.md
      002-database-choice.md

techdocs:
  builder: external
  generator:
    runIn: local
  publisher:
    type: awsS3
    awsS3:
      bucketName: mycompany-techdocs
      region: ap-northeast-2
      credentials:
        roleArn: arn:aws:iam::123456789012:role/techdocs-publisher

# 프론트엔드 플러그인 생성
yarn new --select plugin
 
# 백엔드 플러그인 생성
yarn new --select backend-plugin

import {
  createPlugin,
  createRoutableExtension,
} from '@backstage/core-plugin-api';
import { rootRouteRef } from './routes';
 
export const myPlugin = createPlugin({
  id: 'my-plugin',
  routes: {
    root: rootRouteRef,
  },
});
 
export const MyPluginPage = myPlugin.provide(
  createRoutableExtension({
    name: 'MyPluginPage',
    component: () =>
      import('./components/MyPluginPage').then(m => m.MyPluginPage),
    mountPoint: rootRouteRef,
  }),
);

import React from 'react';
import { Typography, Grid } from '@material-ui/core';
import {
  Header,
  Page,
  Content,
  ContentHeader,
  SupportButton,
} from '@backstage/core-components';
 
export function MyPluginPage() {
  return (
    <Page themeId="tool">
      <Header title="My Custom Plugin" subtitle="조직 특화 기능" />
      <Content>
        <ContentHeader title="Overview">
          <SupportButton>플랫폼 팀에 문의</SupportButton>
        </ContentHeader>
        <Grid container spacing={3}>
          <Grid item xs={12}>
            <Typography variant="body1">
              커스텀 플러그인 콘텐츠가 여기에 표시됩니다.
            </Typography>
          </Grid>
        </Grid>
      </Content>
    </Page>
  );
}

permission:
  enabled: true
  rbac:
    admin:
      superUsers:
        - name: user:default/platform-admin
    policies:
      - permission: catalog.entity.read
        effect: allow
        conditions:
          allOf:
            - resourceType: catalog-entity
      - permission: catalog.entity.delete
        effect: deny
        conditions:
          not:
            allOf:
              - claim: groups
                value: platform-team