콘텐츠로 이동

Panel 앱 만들기

Panel Studio로 시작하십시오. 리포지토리도 설정도 필요하지 않습니다. PlaidCloud에서 앱을 빌드하고 미리 본 다음, 준비가 되면 게시합니다. Studio가 맞지 않는 경우에만 맞춤형 런타임을 선택하십시오.

앱을 열고 새 앱 메뉴를 엽니다. Panel 앱 제목 아래의 Studio는 PlaidCloud 편집기에서 표준 레이아웃으로 앱을 작성하고 게시하며 코드를 대신 보관해 줍니다. 프로젝트의 홈 탭의 앱 및 브랜딩 카드에 있는 Studio 앱 행에서 새 Studio 앱을 선택하거나 테이블에서 시작할 수도 있습니다.

  1. 새 앱 > Studio를 선택합니다.

  2. 이름을 입력합니다. URL 슬러그는 이름에서 자동으로 채워집니다.

  3. 앱을 소유할 프로젝트를 선택합니다. 프로젝트에 대한 편집 액세스 권한이 필요합니다.

  4. 시작 기준에서 앱을 시작할 위치를 선택합니다.

    시작 기준 결과
    빈 앱 app.py와 requirements.txt가 있는 최소한의 앱.
    테이블에서 선택한 테이블을 기반으로 만든 앱.
    뷰에서 프로젝트 뷰를 기반으로 만든 동일한 앱.
    다른 Studio 앱에서 Studio 앱 중 하나의 복사본.
    갤러리에서 워크스페이스가 갤러리에 등록한 앱의 복사본.
  5. 만들기를 선택합니다. Studio에서 새 앱이 열립니다. 테이블이나 뷰의 경우, 첫 페이지를 빌드하는 Weave 프롬프트를 바로 보낼 수 있는 상태로 준비됩니다.

앱을 편집하고 미리 보고 게시하는 방법은 Panel Studio를 참조하십시오.

프로젝트의 테이블 탭에서 시작할 수도 있습니다. 테이블 또는 뷰 하나를 선택한 다음 새로 만들기 메뉴 또는 마우스 오른쪽 버튼 메뉴에서 Panel 앱 만들기를 선택합니다. 프로젝트와 테이블이 이미 선택된 상태로 새 Studio 앱 대화 상자가 열립니다. 이 명령은 프로젝트에 대한 편집 액세스 권한이 있고 프로젝트가 읽기 전용이 아닐 때 사용할 수 있습니다.

새 앱 > 갤러리에서… 를 선택하여 워크스페이스가 등록한 앱을 둘러본 다음, 이것으로 앱 만들기… 를 선택하여 자신의 복사본을 만듭니다. 또는 새 Studio 앱 대화 상자에서 갤러리에서를 선택합니다. 자신의 앱을 등록하는 방법을 포함하여 앱 갤러리를 참조하십시오.

Studio 앱은 대부분의 대시보드와 도구를 포괄합니다. 맞춤형 요구 사항이 있는 경우 새 앱 메뉴에서 다른 런타임 중 하나로 게시하십시오.

  • 브라우저 전용 — 자체 리포지토리를 사용하며, 앱이 뷰어의 브라우저에서 실행됩니다.
  • 서버 기반 — 자체 리포지토리를 사용하며, 앱이 PlaidCloud 서버에서 실행됩니다. 예를 들어 기존 코드나 자체 빌드 프로세스를 재사용하려는 경우에 사용합니다.
  • Dash 앱 — Plotly Dash 앱을 게시합니다. Dash 앱을 참조하십시오.

서버 앱은 git 리포지토리에서 빌드되며 https://<your-tenant-host>/serve/<slug>/에서 제공됩니다. PlaidCloud가 리포지토리의 브랜치를 가리키도록 설정하면, 코드를 컨테이너로 빌드하고 그 안에서 panel serve를 실행하며, 해당 브랜치에 푸시할 때마다 자동으로 다시 빌드합니다.

리포지토리에는 두 가지가 필요합니다. Panel 앱을 빌드하고 .servable()로 표시하는 Python 파일인 진입점, 그리고 선택 사항으로 추가 패키지를 나열한 requirements.txt 입니다. 이 파일은 리포지토리 루트나 진입점 옆에 둘 수 있습니다.

my-panel-app/
├── app.py # entry point — calls .servable()
└── requirements.txt # optional; extra dependencies (repo root or next to app.py)

app.py를 만듭니다.

import panel as pn
pn.extension()
pn.pane.Markdown("# Hello, PlaidCloud 👋\n\nYour first server-side Panel app is running.").servable()

이것으로 완전한 앱입니다. PlaidCloud가 제공하는 것은 .servable() 호출입니다. 렌더링하려는 모든 것은 직접 또는 servable 레이아웃 안에 있는 방식으로 servable로 표시되어 있어야 합니다.

Panel 앱은 대화형입니다. 이 예제는 테이블을 실시간으로 업데이트하는 슬라이더를 추가합니다.

import pandas as pd
import panel as pn
pn.extension()
multiplier = pn.widgets.IntSlider(name="Multiplier", start=1, end=10, value=3)
@pn.depends(multiplier)
def times_table(m):
df = pd.DataFrame({"n": range(1, 6)})
df["result"] = df["n"] * m
return pn.pane.DataFrame(df, index=False)
pn.Column(
"# Times Table",
multiplier,
times_table,
).servable()

이 두 번째 예제는 기본 이미지에 포함되지 않은 pandas를 가져오므로, requirements.txt를 추가하십시오(리포지토리 루트 또는 진입점 옆).

pandas

PlaidCloud는 이미지를 빌드할 때 pip으로 이를 설치합니다. 일반적인 시각화 라이브러리인 plotly, holoviews, hvplot도 기본 이미지에 없으므로, 앱이 가져오는 라이브러리가 있으면 여기에 나열하십시오.

플랫폼이 제공하는 것과 기대하는 것. 앱을 작성할 때 다음 전제를 염두에 두십시오.

  • panel과 bokeh는 플랫폼 기본 이미지에 미리 설치되어 있습니다. requirements.txt에 나열하지 말고, 이전 버전의 Panel로 고정하지 마십시오. 실시간 업데이트 재연결은 최신 버전에 의존합니다.
  • PlaidCloud 클라이언트 라이브러리(plaidcloud-rpc, plaidcloud-utilities)는 미리 설치되어 있습니다. plaidcloud.rpc 또는 plaidcloud.utilities를 직접 가져오고 requirements.txt에는 나열하지 마십시오.
  • requirements.txt는 리포지토리 루트 또는 진입점 옆에 둘 수 있습니다. 공유(모노레포) 리포지토리에서는 각 앱의 종속성을 해당 앱의 폴더에 두십시오. 루트 수준 파일이 있으면 그것도 설치되므로, 공유 종속성은 루트에, 앱별 종속성은 앱 옆에 두십시오.
  • 앱은 읽기 전용 파일 시스템에서 루트가 아닌 사용자로 실행됩니다. 쓰기가 가능한 곳은 /tmp뿐이므로 임시 파일은 그곳에 쓰십시오(대부분의 라이브러리는 이미 $TMPDIR을 따릅니다).
  • 포트, URL 접두사, 호스트를 하드코딩하지 마십시오. PlaidCloud가 이를 할당하고 배포 시점에 주입하므로 .servable()만 호출하면 됩니다.

PlaidCloud의 모양과 바로 사용할 수 있는 필터, 그리드, 차트를 사용하려면 Panel 앱 키트로 앱을 빌드하십시오.

테마 설정: 라이트, 다크 또는 전환

섹션 제목: “테마 설정: 라이트, 다크 또는 전환”

서버 앱은 기본적으로 PlaidCloud의 현대적인 Fast 디자인으로 렌더링됩니다. 플랫폼 전체에 적용되는 깔끔한 Fluent 스타일의 모양입니다. 게시 대화 상자에서 디자인이 이 플랫폼 계층을 제어합니다.

  • FAST — PlaidCloud 기본값입니다. 새 앱과 Fast 템플릿으로 빌드한 앱에 사용하십시오.
  • 기본값 — Panel의 기본 스타일입니다. 기존 앱의 CSS나 시각 요소가 FAST에서 깨지는 경우에 사용하십시오.

앱 코드에서 제어하는 것은 테마, 즉 라이트, 다크 또는 뷰어가 전환할 수 있는 스위치입니다.

테마는 제공하는 템플릿의 속성입니다. Fast 템플릿인 FastListTemplate(단일 열)과 FastGridTemplate(반응형 그리드)은 이를 위해 두 가지 설정을 받습니다.

  • theme — 라이트는 "default", 다크는 "dark"입니다. 이 값을 설정하면 뷰어가 URL에 ?theme=dark를 추가해도 앱이 해당 테마로 고정됩니다.
  • theme_toggle — True이면 머리글에 라이트/다크 스위치가 표시되고, False이면 숨겨집니다. 기본값은 True입니다. 스위치를 숨기는 것만으로는 테마가 고정되지 않으므로 위의 theme으로 고정하십시오. 그런 다음 theme_toggle=False를 설정하면 뷰어에게 아무것도 바꾸지 못하는 스위치가 보이지 않습니다.

앱에 맞는 패턴을 선택하십시오.

라이트만 — 보통 밝은 배경에 맞게 직접 스타일을 지정하는 밀도 높은 보고서와 재무 테이블에 가장 적합합니다.

import panel as pn
pn.extension("tabulator")
pn.template.FastListTemplate(
title="Sales Dashboard",
theme="default", # light
theme_toggle=False, # hide the switch
main=[...],
).servable()

다크만:

pn.template.FastListTemplate(
title="Ops Monitor",
theme="dark",
theme_toggle=False,
main=[...],
).servable()

뷰어가 선택 — 기본값은 라이트이며 머리글에 스위치가 있습니다. 토글을 따르도록 theme을 생략하십시오.

pn.template.FastListTemplate(
title="Explorer",
theme_toggle=True,
main=[...],
).servable()

다크를 허용한다면 테이블도 다크 모드에 맞게 만드십시오. 밝은 테이블 테마(theme="bootstrap")로 고정된 Tabulator나 background: #fff와 같이 밝은 색을 하드코딩한 사용자 지정 CSS는 어두운 페이지에서 읽을 수 없는 흰색 블록으로 렌더링됩니다. pn.widgets.Tabulator(..., theme="fast")처럼 앱을 따르는 테이블 테마를 사용하고 밝은 색을 하드코딩하지 마십시오. 보고서가 밝은 배경에 맞게 크게 직접 스타일링되어 있다면 대신 라이트로 고정하십시오(위의 첫 번째 패턴).

템플릿이 없는 일반 앱인 pn.Column(...).servable()은 Panel의 기본값을 따르며 이러한 설정의 영향을 받지 않습니다. 명시적으로 제어하려면 템플릿을 사용하십시오.

리포지토리는 PlaidCloud의 git 연결을 통해 접근할 수 있어야 합니다. 코드가 PlaidCloud Git에 있으면 Tools > Connections 아래에서 관리형 PlaidCloud Git 연결을 만드십시오. 서버 URL이나 자격 증명이 필요하지 않습니다. 빈 리포지토리에서 제공되는 앱까지의 전체 과정은 PlaidCloud Git에서 Panel 앱 배포를 참조하십시오.

  1. 새 앱 > 서버 기반를 선택하여 서버 Panel 앱 게시 대화 상자를 엽니다. 설정은 섹션별로 그룹화되어 있습니다.
  2. 디렉터리 설정에서:
    • 앱 이름 — 목록에 표시되는 표시 이름입니다.
    • URL 슬러그 — 앱의 URL이자 내부 이름이므로 유효한 DNS 레이블이어야 합니다. 소문자, 숫자, 하이픈을 사용하고 문자로 시작하며 40자 이하여야 합니다(예: sales-dashboard). 대화 상자는 게시하기 전에 이를 확인합니다.
    • 메모 — 선택적 설명입니다.
    • 프로젝트 — 앱을 소유하는 프로젝트입니다. 앱의 브랜딩을 제공하며 앱 테이블의 기본 프로젝트입니다. 게시한 후에는 여기에서 변경할 수 없으며, Assign을 사용하십시오.
  3. Git 연결 및 게시 감시기에서:
    • Git 연결 — 앱의 리포지토리를 보관하는 연결입니다.
    • 브랜치 — 빌드할 브랜치입니다. 이 브랜치에 푸시하면 앱이 자동으로 다시 빌드되고 다시 배포됩니다.
    • 진입점 — Panel이 제공해야 하는 .py 파일입니다(app.py).
  4. 런타임에서:
    • 앱의 컨테이너가 요청해야 하는 CPU와 메모리.

      리소스(CPU/메모리)를 줄이면 앱이 더 빠르게 스케줄되고 콜드 스타트됩니다.

    • 디자인 — PlaidCloud의 현대적인 디자인을 사용하려면 FAST를 선택하고, 앱의 CSS가 Panel의 기본 스타일을 기대하는 경우 기본값을 선택합니다.

    • 유휴 시간(분) — 트래픽이 없을 때 앱이 0으로 축소되기 전까지 준비 상태를 유지하는 시간입니다. 기본값은 5분입니다.

    • 공개 액세스 허용 — 인증되지 않은 액세스를 허용하려면 선택합니다. 선택하지 않으면 뷰어가 테넌트에 로그인해야 합니다.

  5. 고급 (임베디드 서비스) 아래 — 선택 사항입니다. 기본적으로 앱은 PlaidCloud 테넌트에서만 제공됩니다. 다른 사이트에 임베드하려면 도메인 추가를 클릭하고 앱을 로드할 수 있는 각 도메인을 행마다 하나씩 입력하십시오. 스킴이나 경로 없이 호스트만 입력합니다(예: example.com 또는 app.example.com:8443). 앱을 다른 곳에 임베드하는 경우가 아니라면 목록을 비워 두십시오.
  6. 게시를 클릭합니다.

게시하면 앱이 빌드되며, 목록에 상태가 표시되고 자동으로 업데이트됩니다. 각 상태의 의미, 앱이 준비되면 여는 방법, 게시를 취소하지 않고 다시 빌드를 트리거하는 방법은 Panel 앱 사용을 참조하십시오.

앱의 URL은 빌드 상태가 준비됨이 된 후에야 작동하며, 유휴 상태였다가 처음 요청하면 앱이 시작되며, 그동안 PlaidCloud 로딩 화면이 잠시 표시됩니다.

고급: 로컬에서 PlaidCloud와 동일하게 구성

섹션 제목: “고급: 로컬에서 PlaidCloud와 동일하게 구성”

기술 사용자는 PlaidCloud가 사용하는 것과 같은 입력으로 앱을 빌드하고 테스트할 수 있습니다. 게시하거나 다시 빌드를 클릭하기 전에 할 수 있는 가장 가까운 로컬 검사입니다.

PlaidCloud는 선택한 git 브랜치에서 다음의 생성된 Dockerfile로 빌드합니다. 로컬에서 같은 내용을 Dockerfile.plaidcloud-panel로 사용하십시오.

FROM us-docker.pkg.dev/plaidcloud-build/panel-base/platform-panel-base:0.5.1
USER root
COPY . /app
RUN if [ -f /app/requirements.txt ]; then pip install --no-cache-dir -r /app/requirements.txt; fi
# If your entry point is in a subfolder, PlaidCloud also installs that folder's requirements.txt,
# after the root one (so a per-app pin wins). Replace <app-folder> with your entry point's folder,
# or drop this line if your app is at the repository root.
RUN if [ -f "/app/<app-folder>/requirements.txt" ]; then pip install --no-cache-dir -r "/app/<app-folder>/requirements.txt"; fi
USER 10001

서버 빌드와 일치시키려면:

  1. 브랜치에서 선택한 것과 같은 브랜치를 체크아웃합니다.
  2. COPY . /app이 PlaidCloud와 일치하도록 리포지토리 루트에서 빌드를 실행합니다.
  3. 선택적 종속성은 리포지토리 루트 또는 진입점 옆의 requirements.txt에 둡니다. 둘 다 설치되며, 앱 폴더의 것이 마지막에 설치됩니다(앱별 고정 버전이 우선하도록).
  4. 진입점에서 선택한 것과 같은 진입점 경로를 사용합니다.
터미널 창
docker build \
-f Dockerfile.plaidcloud-panel \
-t local-panel-app:plaidcloud \
.

배포된 이미지는 기본 이미지 진입점을 재정의하지 않습니다. PlaidCloud가 주입하는 환경 변수로 panel serve를 실행합니다. 같은 런타임 계약으로 빌드된 이미지를 테스트하십시오.

터미널 창
docker run --rm \
--cpus 0.5 \
--memory 512m \
-p 5006:5006 \
-e APP_PATH=/app/app.py \
-e PANEL_PREFIX=/serve/local \
-e PANEL_PORT=5006 \
-e PANEL_ORIGIN=localhost:5006 \
-e PANEL_KEEP_ALIVE_MS=25000 \
-e PLAID_PANEL_DESIGN=fast \
local-panel-app:plaidcloud

http://localhost:5006/serve/local/을 엽니다.

테스트할 때 게시 대화 상자의 설정과 일치시키십시오.

  • 진입점은 APP_PATH=/app/<entry-point>에 대응합니다.
  • CPU와 메모리는 Docker의 --cpus 및 --memory 제한에 대응합니다.
  • 디자인: FAST는 PLAID_PANEL_DESIGN=fast에 대응합니다.
  • 디자인: 기본값은 PLAID_PANEL_DESIGN을 생략하는 것을 의미합니다.
  • 유휴 시간(분) 은 배포된 축소 시간 창에 대응합니다. 로컬 Docker에서는 적용되지 않지만, 앱은 동일한 Panel 웹소켓 keepalive 및 세션 정리 설정을 그대로 사용합니다.
  • 임베디드 서비스 도메인은 PANEL_ORIGIN에 대응합니다. 둘 이상의 호스트를 테스트해야 하면 공백으로 구분한 목록을 사용하십시오.

컨테이너가 필요하지 않다면 로컬 Python 환경에서 서비스 계층을 테스트할 수도 있습니다. 같은 requirements.txt를 설치하고 플랫폼 환경 변수를 설정한 다음, 배포된 이미지가 사용하는 것과 같은 플래그로 panel serve를 실행합니다.

터미널 창
export APP_PATH=app.py
export PANEL_PREFIX=/serve/local
export PANEL_PORT=5006
export PANEL_ORIGIN=localhost:5006
export PANEL_KEEP_ALIVE_MS=25000
export PLAID_PANEL_DESIGN=fast
panel serve "$APP_PATH" \
--address 0.0.0.0 \
--port "$PANEL_PORT" \
--prefix "$PANEL_PREFIX" \
--allow-websocket-origin "$PANEL_ORIGIN" \
--num-procs 1 \
--keep-alive "$PANEL_KEEP_ALIVE_MS" \
--unused-session-lifetime 15000 \
--index "$(basename "$APP_PATH" .py)"

http://localhost:5006/serve/local/을 엽니다.

배포된 기본 모양과 일치시키려면 PLAID_PANEL_DESIGN=fast를 사용하십시오. 게시 대화 상자의 기본값 디자인 옵션을 테스트하려면 PLAID_PANEL_DESIGN을 설정하지 않은 상태로 같은 명령을 실행하십시오. PANEL_PREFIX, PANEL_ORIGIN, --keep-alive, --unused-session-lifetime은 그대로 유지하십시오. 이것들은 배포된 런타임 계약의 일부입니다.

WASM 앱은 미리 빌드된 HTML 파일에서 브라우저로 실행됩니다.

  1. 새 앱 > 브라우저 전용를 선택하여 서버리스 Panel 앱 게시 대화 상자를 엽니다.
  2. 앱 이름과 버전을 입력합니다.
  3. 앱 HTML 위치, 즉 문서 계정에 있는 HTML 파일을 선택합니다.
  4. 앱 URL 슬러그와 선택 사항인 메모를 입력합니다.
  5. 게시를 클릭합니다. WASM 앱에는 빌드 단계가 없으며 즉시 제공됩니다.