@microsoft/rayfin-guide 1.1.0 → 1.33.0-beta.0

package/assets/docs/app-backend/deploy.md

@@ -0,0 +1,257 @@
+---
+sidebar_position: 45
+---
+
+# Deploy to Microsoft Fabric
+
+Rayfin deploys your entire application stack to Microsoft Fabric with a single command.
+The CLI handles authentication, resource provisioning, database schema application, and static content hosting so you can go from local development to a live URL in minutes.
+
+## Prerequisites
+
+- A Rayfin project with a `rayfin/rayfin.yml` configuration file.
+- A Microsoft account with access to a Fabric workspace.
+
+## Sign in
+
+Authenticate with your Microsoft Entra ID account before deploying:
+
+```bash
+npx rayfin login
+```
+
+The CLI opens a browser window for interactive sign-in.
+After authentication, tokens are stored securely in the OS keychain under `~/.rayfin/`.
+
+Check your sign-in status at any time:
+
+```bash
+npx rayfin login status
+```
+
+To force an account selection prompt when multiple accounts are available:
+
+```bash
+npx rayfin login --select
+```
+
+### Non-interactive login
+
+Authenticate as a service principal using client credentials when interactive browser login is not available or desired:
+
+```bash
+npx rayfin login --service-principal \
+  --client-id <app-registration-client-id> \
+  --client-secret <secret> \
+  --tenant <tenant-id>
+```
+
+Credentials are persisted to `~/.rayfin/` so all subsequent commands in the same pipeline job authenticate automatically.
+No browser or user interaction is required.
+
+Alternatively, set the `RAYFIN_TOKEN` environment variable with a pre-acquired Bearer token to bypass MSAL entirely.
+See [Environment variables](../cli/environment-variables.md#shell-only-variables) for details.
+
+## Deploy with `rayfin up`
+
+Run the following command from your project root:
+
+```bash
+npx rayfin up
+```
+
+If you are not signed in, the CLI launches an interactive login flow automatically.
+
+### What `rayfin up` does
+
+The command performs these steps in order:
+
+1. **Creates a Rayfin item** in your Fabric workspace (or reuses the existing one on subsequent deploys).
+1. **Retrieves the publishable key** from the remote service.
+1. **Syncs runtime settings** from your `rayfin.yml` to the remote service, including auth configuration and service flags.
+1. **Applies the database schema** generated from your TypeScript data model decorators.
+1. **Builds and deploys static content** if `staticHosting` is enabled in `rayfin.yml` — runs your build command, packages the output folder into a ZIP, and uploads it.
+1. **Persists deployment details** to `rayfin/.deployments.json` and merges `RAYFIN_PUBLIC_*` variables into `rayfin/.env` for subsequent deploys.
+
+After deployment, the CLI prints:
+
+- The **hosting URL** where your app is live.
+- A **Fabric portal link** to manage the deployment.
+- The **deployment ID** for reference.
+
+### Deployment output
+
+Each deployment is recorded in `rayfin/.deployments.json` (the registry of every workspace you have deployed to from this project), and the corresponding `RAYFIN_PUBLIC_*` variables are merged into `rayfin/.env` so subsequent commands and your frontend pick up the same values.
+
+For frontend frameworks, the CLI also runs `rayfin env` to emit a framework-specific `.env.local` (e.g. for Vite) before the static build. That file is what your client code reads at runtime.
+
+```text title="rayfin/.deployments.json"
+{
+  "active": "myworkspace",
+  "deployments": {
+    "myworkspace": {
+      "fabricItemId": "7db00cb9-f630-4ecf-8fc9-942e60af5d78",
+      "fabricApiUrl": "https://...",
+      "fabricWorkspaceId": "8b17cf64-3c12-46ac-a572-192732c32641",
+      "fabricTenantId": "...",
+      "publishableKey": "pk-nua-EHihY2jz71V65YB4",
+      "fabricPortalUrl": "https://dxt.fabric.microsoft.com/",
+      "hostingUrl": "https://silky-sand-4924b3ad1f-centraluseuap.webapp.rayfingwdev.com",
+      "deployedAt": "2026-04-28T01:15:50.514Z"
+    }
+  }
+}
+```
+
+The matching `.env.local` (auto-generated by `rayfin env --framework vite`) looks like:
+
+```bash title=".env.local"
+VITE_FABRIC_ITEM_ID=7db00cb9-f630-4ecf-8fc9-942e60af5d78
+VITE_RAYFIN_API_URL=https://...
+VITE_FABRIC_WORKSPACE_ID=8b17cf64-3c12-46ac-a572-192732c32641
+VITE_RAYFIN_PUBLISHABLE_KEY=pk-nua-EHihY2jz71V65YB4
+VITE_FABRIC_PORTAL_URL=https://dxt.fabric.microsoft.com/
+```
+
+| Variable | Description |
+| --- | --- |
+| `VITE_FABRIC_ITEM_ID` | The Fabric item ID for this deployment. |
+| `VITE_RAYFIN_API_URL` | Full URL to the deployed Rayfin backend API. |
+| `VITE_FABRIC_WORKSPACE_ID` | The Fabric workspace ID containing the deployment. |
+| `VITE_RAYFIN_PUBLISHABLE_KEY` | Publishable key used by the Rayfin client for authentication. |
+| `VITE_FABRIC_PORTAL_URL` | URL to the Fabric portal for managing the deployment. |
+| `VITE_RAYFIN_HOSTING_URL` | Public URL where your static content is hosted. |
+
+### Authentication after deployment
+
+Only **Fabric brokered authentication (Entra SSO)** is supported on deployed applications. Email and password authentication is available during local development but does not work after deploying to Fabric.
+
+Ensure your `rayfin.yml` has Fabric auth enabled before running `rayfin up`:
+
+```yaml
+services:
+  auth:
+    enabled: true
+    fabric:
+      enabled: true
+```
+
+### Preview without deploying
+
+Use `-n, --dry-run` to see what the CLI would do without creating or modifying any resources:
+
+```bash
+npx rayfin up -n
+```
+
+### Skip specific services
+
+Use `--exclude-services <names>` to skip the build/package/deploy phase for supported services without touching the rest of the deployment.
+The runtime settings POST still reflects your `rayfin.yml`, so the backend is never silently reconfigured.
+The only currently supported value is `staticHosting`; other names fail with a clear error.
+
+The canonical use case is local development where Vite serves the frontend locally, so you want the backend deployed but not the static bundle:
+
+```bash
+npx rayfin up --exclude-services staticHosting
+```
+
+The samples and templates use this flag in their `npm run dev` script.
+
+## Apply database changes remotely
+
+After updating your data models, push schema changes to the remote database without redeploying the full stack:
+
+```bash
+npx rayfin up db apply
+```
+
+If the schema change involves potentially destructive operations (dropping columns, renaming tables), the CLI warns you and refuses to proceed.
+Use `--force` to override the safety check:
+
+```bash
+npx rayfin up db apply --force
+```
+
+## Redeploy static content
+
+When you have only changed frontend code, redeploy static content independently for a faster iteration cycle:
+
+```bash
+npx rayfin up staticapp deploy
+```
+
+This runs your configured `buildCommand`, packages the output, and uploads it to the remote service.
+
+To skip the build step and deploy existing output:
+
+```bash
+npx rayfin up staticapp deploy --skip-build
+```
+
+## Check deployment status
+
+View the current state of your Fabric deployment:
+
+```bash
+npx rayfin up status
+```
+
+Add `--json` for machine-readable output:
+
+```bash
+npx rayfin up status --json
+```
+
+## Sign out
+
+Clear cached credentials when you are done or need to switch accounts:
+
+```bash
+npx rayfin logout
+```
+
+## Subsequent deployments
+
+After the first deploy, `rayfin/.deployments.json` records the deployment metadata and the matching `RAYFIN_PUBLIC_*` values are merged into `rayfin/.env`. The frontend `.env.local` (generated by `rayfin env --framework vite`) reflects those values (`VITE_FABRIC_ITEM_ID`, `VITE_FABRIC_WORKSPACE_ID`, and the API endpoint).
+Running `npx rayfin up` again updates the same deployment rather than creating a new one.
+
+For targeted updates, use the subcommands:
+
+| Command | What it updates |
+| --- | --- |
+| `npx rayfin up` | Everything: settings, database, and static content. |
+| `npx rayfin up db apply` | Database schema only. |
+| `npx rayfin up staticapp deploy` | Static content only. |
+
+## Troubleshooting
+
+### Deployment fails with 401 or 403
+
+Your session may have expired. Run `npx rayfin login` to reauthenticate, then retry `npx rayfin up`.
+
+### Database apply reports destructive changes
+
+The CLI blocks schema changes that could cause data loss. Review the listed operations and use `npx rayfin up db apply --force` only after confirming you accept the data loss.
+
+### Deployment fails with "Dialect is required"
+
+Enabling `data: enabled: true` in `rayfin.yml` without specifying a `dialect` causes a 400 error during `rayfin up`.
+Add `dialect: mssql` (or `postgresql` for local dev) under the `data` section:
+
+```yaml
+services:
+  data:
+    enabled: true
+    dialect: mssql
+```
+
+### Static deploy exceeds size limit
+
+The compressed archive must not exceed 100 MB. Optimize your build output by excluding source maps and large development assets, or move binary files to Rayfin storage.
+
+### GraphQL returns "Internal server error" after deploy
+
+If `rayfin up` succeeded but the app fails with GraphQL errors at runtime, check for `@text()` fields without `max` in your entity definitions.
+These generate `NVARCHAR(MAX)` columns on MSSQL, which can prevent DAB from building its GraphQL schema.
+Add explicit `max` constraints (e.g., `@text({ max: 200 })`), then redeploy with `npx rayfin up db apply --force`.

package/assets/docs/app-backend/index.md

@@ -0,0 +1,126 @@
+---
+sidebar_position: 2
+title: Fabric Data App in Microsoft Fabric
+---
+
+A **Fabric data app** is a Fabric item that hosts your Rayfin application as a managed service.
+When you create a Fabric data app in a Fabric workspace, Fabric provisions and manages the backend infrastructure — database, authentication, static hosting, and API endpoints — so you can focus on your application code.
+
+## What is a Fabric data app?
+
+A Fabric data app is the Fabric representation of your Rayfin project.
+It contains all the services your application needs, exposed through a single Rayfin endpoint.
+
+```mermaid
+flowchart TD
+  AppBackend[Fabric Data App] --> Database[(SQL Database)]
+  AppBackend --> Auth[Authentication]
+  AppBackend --> StaticHosting[Static Content]
+  AppBackend --> WebService[Rayfin WebService]
+  WebService --> DataApi[Data API / GraphQL]
+  DataApi --> Database
+```
+
+Each Fabric data app lives inside a Fabric workspace.
+You can create multiple Fabric data apps in the same workspace for different applications or environments.
+
+## Prerequisites
+
+### Fabric capacity
+
+Your workspace must have Fabric capacity assigned. When creating a new workspace, select a Fabric capacity to associate with it. Rayfin services consume capacity units from the assigned capacity.
+
+### Tenant admin settings
+
+A Fabric tenant administrator must enable the Fabric data app workload before users can create items.
+
+1. Sign in to the [Fabric admin portal](https://app.fabric.microsoft.com/admin-portal).
+2. Navigate to **Tenant settings**.
+3. Under **Fabric Apps (preview)**, toggle the setting to **Enabled**.
+4. Choose whether to enable for the entire organization or specific security groups.
+5. Click **Apply**.
+
+Changes may take a few minutes to propagate.
+
+## Child services
+
+When you deploy your application with `rayfin up`, Fabric provisions child services based on your `rayfin.yml` configuration.
+These child services appear as child items under the Fabric data app in the Fabric portal.
+
+| Child service | What it provides | Portal capabilities |
+| --- | --- | --- |
+| **SQL Database** | MSSQL database with your schema applied from TypeScript data model decorators. | View database, run queries with the query editor, copy connection string. The database is read-only in the portal — schema changes must come from your code via `rayfin up`. |
+| **Authentication** | Fabric brokered auth using Microsoft Entra ID (SSO). Users sign in through their existing Fabric identity. | View authenticated users inthe SQL Database. |
+| **Static Content** | Your built frontend assets (HTML, CSS, JS) served at a public URL. This uses OneLake storage. | View hosting URL. Assets are updated on each deploy. |
+
+## Rayfin endpoint
+
+Each Fabric data app has a single Rayfin endpoint that provides access to all services:
+
+```text
+https://<your-app>-app.rayfin.windows.net/
+```
+
+The endpoint exposes paths for each service:
+
+| Path | Service |
+| --- | --- |
+| `/api/graphql` | Data API (GraphQL) — used by `RayfinClient` for CRUD operations |
+| `/auth` | Authentication service |
+| `/storage` | File storage |
+
+Your frontend application uses this endpoint via the `VITE_RAYFIN_API_URL` environment variable, which is generated into `.env.local` from `rayfin/.env` after deployment.
+
+## Deployment
+
+You deploy your application to a Fabric data app using the `rayfin up` CLI command or the **Project Rayfin: Up: Deploy to Fabric** command in VS Code.
+
+### What happens during deployment
+
+1. **Item creation** — The CLI creates a Fabric data app in your Fabric workspace (first deploy) or connects to the existing one (subsequent deploys).
+2. **Publishable key** — A publishable key is retrieved from the remote service and stored in `rayfin.yml`. **This cannot be modified.**
+3. **Settings sync** — Runtime settings from `rayfin.yml` are pushed to the remote service, including auth configuration and enabled services.
+4. **Schema application** — The database schema generated from your TypeScript decorators is applied to the remote MSSQL instance.
+5. **Static content** — If `staticHosting` is enabled, the CLI runs your build command, packages the output, and uploads it.
+6. **Output** — Deployment details are recorded in `rayfin/.deployments.json` and the matching `RAYFIN_PUBLIC_*` values are merged into `rayfin/.env` for use by your frontend and subsequent deploys.
+
+## Management in the Fabric portal
+
+After deployment, you can manage your Fabric data app directly in the Fabric portal.
+
+### Viewing item properties
+
+Open the Fabric data app in the portal to see:
+
+- **Rayfin endpoint** — The base URL for all services. Copy it for use in environment configuration.
+- **App URL** — The public URL where your static content is hosted.
+- **Fabric portal link** — Direct link to manage the deployment.
+
+### Managing child items
+
+Click into the Fabric data app to see its child services:
+
+- **SQL Database** — Opens the Fabric SQL query editor. You can run read queries against your data. Schema changes made directly in the portal are overwritten on the next `rayfin up` deploy.
+- **Authentication** — View and manage authenticated users in **Users** table in the SQL Database.
+
+### Permissions
+
+Workspace roles do not supersede item-level permissions.
+To share an app with someone in your organization, they need **Run and interact** permission, that is, **Read and execute**, to run the app and invoke the backend APIs.
+
+The table below shows what each permission level allows:
+
+| Permission | What it allows |
+| --- | --- |
+| **Run and interact** (default) | Open and use the deployed application. All workspace members receive this level by default. |
+| **Edit (Write)** | Modify the Fabric data app — deploy code with `rayfin up`, apply schema changes, update settings, and manage child services. Requires **contributor** or **admin** role on the workspace. |
+| **Reshare** | Grant other users access to the Fabric data app. Requires **admin** role on the workspace. |
+
+Learn more about [Workspace roles](https://learn.microsoft.com/fabric/fundamentals/roles-workspaces)
+
+## Next steps
+
+- [Pricing and capacity usage](./pricing.md) — Understand what consumes Fabric capacity and how billing works.
+- [Create a Fabric data app](../getting-started/create-rayfin-item.md) — Step-by-step guide to creating your first item in the Fabric portal.
+- [Deploy to Microsoft Fabric](./deploy.md) — Detailed deployment commands and troubleshooting.
+- [Fabric Brokered Auth](../auth/fabric.md) — How Fabric SSO authentication works.

package/assets/docs/app-backend/pricing.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 2
+title: Pricing and capacity usage
+---
+
+Fabric data apps run on Microsoft Fabric capacity.
+There are **no additional Rayfin-specific charges** — you pay only for the Fabric capacity units (CUs) consumed by the underlying services your application uses.
+
+## How billing works
+
+Fabric uses a universal billing model based on **Capacity Units (CUs)**.
+Every operation performed by a Fabric data app child service consumes CUs from the Fabric capacity assigned to your workspace.
+
+Your workspace must have a Fabric capacity associated with it.
+CU consumption is tracked in the [Microsoft Fabric Capacity Metrics app](https://learn.microsoft.com/fabric/enterprise/metrics-app) where you can monitor usage per item and per operation.
+
+## What consumes capacity
+
+A Fabric data app uses three Fabric services that consume CUs:
+
+### SQL Database
+
+The SQL Database child item consumes CUs for compute and storage.
+
+| Operation | What it covers | Billing meter | Type |
+| --- | --- | --- | --- |
+| **SQL Usage** | Compute for all SQL queries, modifications, and data processing — includes queries from your application's GraphQL API and any queries you run in the Fabric portal query editor. | SQL database in Microsoft Fabric Capacity Usage CU | Interactive |
+| **Allocated SQL Storage** | Dynamically allocated storage for tables, indexes, transaction logs, and metadata. Fully integrated with OneLake. | SQL Storage Data Stored | Background |
+
+One Fabric CU equals 0.383 SQL database vCores.
+
+### GraphQL API
+
+Every GraphQL query (read) and mutation (write) made by your application's `RayfinClient` consumes CUs.
+The consumption rate is ten CUs per hour of request and response processing time.
+
+| Operation | What it covers | Billing meter | Type |
+| --- | --- | --- | --- |
+| **Query** | Compute for all GraphQL queries (reads) and mutations (writes) performed by API clients against your data models. | API for GraphQL Query Capacity Usage CU | Interactive |
+
+For more details, see [Fabric API for GraphQL](https://learn.microsoft.com/en-us/fabric/enterprise/fabric-operations#fabric-api-for-graphql) in the Fabric operations documentation.
+
+### OneLake storage (static content)
+
+When static hosting is enabled, your built frontend assets (HTML, CSS, JS) are stored in OneLake and served from a public URL.
+OneLake storage and the read/write operations to serve content consume CUs.
+
+| Operation | What it covers | Billing meter | Type |
+| --- | --- | --- | --- |
+| **OneLake Read** | Read operations when serving static content to end users. | OneLake Read Operations Capacity Usage CU | Background |
+| **OneLake Write** | Write operations when deploying or updating static content via `rayfin up`. | OneLake Write Operations Capacity Usage CU | Background |
+| **OneLake Storage** | Storage of static content files in OneLake. | OneLake Storage | Background |
+
+## What does not consume additional capacity
+
+The following Fabric data app capabilities do **not** incur separate CU charges at this time:
+
+- **Rayfin WebService** — The application backend service that handles API routing and authentication.
+- **Authentication** — Fabric brokered auth (Entra SSO) sign-in and session management.
+- **Deployment operations** — Running `rayfin up` to deploy your application does not have its own CU charge beyond the SQL and OneLake operations it triggers.
+
+## Further reading
+
+- [Fabric operations](https://learn.microsoft.com/en-us/fabric/enterprise/fabric-operations) — Full list of Fabric operations and their capacity consumption rates.
+- [Microsoft Fabric Capacity Metrics app](https://learn.microsoft.com/en-us/fabric/enterprise/metrics-app) — Monitor and understand your capacity usage.
+- [Fabric Data App in Fabric](./index.md) — Overview of the Fabric data app and its child services.