starj-portal 개발 키트

테마

포탈에 설치하기 ​

BP 산출물 디렉터리를 포탈의 설치 디렉터리에 놓으면, 포탈이 다음 부팅에 스캔해 등록한다. 포탈 이미지를 다시 빌드하지 않는다.

1. 넘기는 것 ​

build-and-package.md에서 만든 dist/ 디렉터리 전체다. 압축해서 넘기는 것이 보통이다.

bash
tar czf hello-bp-1.0.0.tgz -C dist .

함께 전달하면 좋은 것:

항목왜
BP id와 버전설치 위치와 업그레이드 판단의 기준
요구하는 호스트 계약 범위대상 포탈이 그 범위를 만족하는지 미리 대조할 수 있다
지원 DB 방언운영 DB가 목록에 없으면 적재되지 않는다
필요한 외부 연결포탈 관리자가 미리 등록해 두어야 하는 것들

2. 설치 (운영자가 하는 일) ​

bash
# <설치 디렉터리>는 포탈이 스캔하도록 설정된 경로다 (환경변수로 지정)
mkdir -p <설치 디렉터리>/hello-bp
tar xzf hello-bp-1.0.0.tgz -C <설치 디렉터리>/hello-bp

배치 결과는 이런 모양이 된다.

<설치 디렉터리>/
  hello-bp/
    bp-manifest.yaml
    backend/index.mjs
    backend/prisma/<provider>/{schema.prisma, migrations/}
    frontend/bundle.js

컨테이너 배포라면 이 디렉터리를 읽기 전용 볼륨으로 마운트하는 것이 표준이다.

3. 포탈이 부팅 시 하는 일 ​

순서대로 진행하며, 어느 단계에서 걸리든 그 BP만 건너뛰고 포탈은 정상적으로 뜬다.

  1. 설치 디렉터리의 하위 디렉터리를 열거한다
  2. 각 bp-manifest.yaml을 읽는다 — apiVersion을 모르면 건너뜀
  3. runtime.hostContract를 포탈의 계약 버전과 대조 — 안 맞으면 건너뜀
  4. backend.database.providers에 실행 중인 방언이 있는지 확인 — 없으면 건너뜀
  5. backend.entry를 동적 import하고 register(host)를 호출 — 없거나 던지면 건너뜀
  6. 반환된 능력 표면으로 화면·메뉴·카드·기본 권한을 등록(upsert)한다
  7. 새 버전이면 마이그레이션을 적용하고 onInstall 훅을 호출한다

"배포했는데 아무 일도 안 일어난다"는 이 중 어딘가에서 조용히 걸린 것이다. 포탈 로그에 건너뛴 이유가 남으므로 그것부터 본다 — troubleshooting.md.

4. 설치 이후 — 관리자가 하는 일 ​

설치(discovery)와 사용 가능 상태는 별개다.

단계누가내용
설치자동부팅 스캔으로 카탈로그에 등록. 포탈 전체 단위
활성화관리자도메인별로 활성화해야 화면·API가 열린다
권한 부여관리자자동 생성된 권한 템플릿을 사용자에게 부여

defaultAuthorities가 만드는 것은 권한의 정의까지다. 사용자에게 부여하는 것은 언제나 관리자의 판단이다 — 설치했는데 화면이 안 보인다면 대개 이 두 단계가 남은 것이다.

5. 업그레이드 ​

같은 위치에 새 버전을 덮어쓰고 포탈을 재기동한다.

  • bp-manifest.yaml의 version이 올라가야 마이그레이션과 onInstall이 다시 돈다.
  • id는 바꾸지 않는다 — upsert 기준이라 바꾸면 기존 레코드와 이어지지 않고 새 BP로 등록된다.
  • apps[].id / menu[].id도 마찬가지다. 이전 버전에서 쓰던 id를 유지해야 화면과 권한이 이어진다.
  • 관리자가 옮겨 놓은 메뉴 배치는 덮어쓰지 않는다.
  • 매니페스트에서 사라진 App·카드는 삭제되지 않고 숨김 처리된다. 되돌리면 되살아난다.

6. 비활성화·제거 ​

  • 비활성화는 도메인별로 이뤄지며, 권한 부여 기록은 보존된다(재활성화 시 복원).
  • 나를 required로 의존하는 활성 BP가 있으면 비활성화가 차단된다.
  • 디렉터리를 지우면 다음 부팅에 적재되지 않는다. 데이터는 남는다 — 정리는 별도 판단이다.