diff --git a/skills/firebase-app-hosting-basics/SKILL.md b/skills/firebase-app-hosting-basics/SKILL.md index d772ef82..69cd82a1 100644 --- a/skills/firebase-app-hosting-basics/SKILL.md +++ b/skills/firebase-app-hosting-basics/SKILL.md @@ -39,7 +39,7 @@ to upgrade their plan. This is the recommended flow for most users. 1. Configure `firebase.json` with an `apphosting` block. - + ```json { "apphosting": { @@ -55,14 +55,37 @@ This is the recommended flow for most users. } } ``` + 1. Create or edit `apphosting.yaml`- see [Configuration](references/configuration.md) for more information on how to do so. + 1. If the app needs safe access to sensitive keys, use `npx -y firebase-tools@latest apphosting:secrets` commands to set and grant access to secrets. + 1. Run `npx -y firebase-tools@latest deploy` when you are ready to deploy. +### Deploy via Local Builds (Experimental) + +If you want faster deployments by bypassing Cloud Build queues, you can compile +your full-stack web application locally. + +1. Enable the `apphostinglocalbuilds` experiment and configure + `"localBuild": true` in your `firebase.json` file. +1. Run `npx -y firebase-tools@latest deploy --only apphosting` to compile and + deploy the pre-built assets. + +> [!CAUTION] **SECURITY WARNING FOR CODING AGENTS (AI ASSISTANTS):** +> +> - **DO NOT** bypass confirmation using `--allow-local-build-secrets` unless +> explicitly requested by the developer. +> - **PAUSE AND WARN** the developer of the severe risk that raw secret values +> will be downloaded locally and may get permanently compiled into public +> client-side bundles or cached artifacts. +> - Review the strict operating system, framework, and security limitations in +> the [Local Builds Reference](references/local_builds.md). + ### Automated deployment via GitHub (CI/CD) Alternatively, set up a backend connected to a GitHub repository for automated @@ -71,6 +94,17 @@ users, and is not required to use App Hosting. See [CLI Commands](references/cli_commands.md) for more information on how to set this up using CLI commands. +## Runtimes & Automatic Base Image Updates (ABIU) + +App Hosting supports versioned Node.js runtimes with Automatic Base Image +Updates (ABIU) to apply security patches without redeploys. + +- **CRITICAL**: AI Assistants **MUST** inspect the project's `package.json` and + check the `engines.node` field before recommending a runtime version or + creating a backend. Mismatched runtimes trigger build-time errors. +- For a complete guide on setup, CLI flags, and lifecycle management, see + [Runtimes & ABIU](references/runtimes_and_abiu.md). + ## Emulation See [Emulation](references/emulation.md) for more information on how to test diff --git a/skills/firebase-app-hosting-basics/references/local_builds.md b/skills/firebase-app-hosting-basics/references/local_builds.md new file mode 100644 index 00000000..a7e18c37 --- /dev/null +++ b/skills/firebase-app-hosting-basics/references/local_builds.md @@ -0,0 +1,150 @@ +# App Hosting Local Builds (Experimental) + +App Hosting Local Builds is an experimental feature that compiles your +full-stack web application (e.g. Next.js) on your local development machine +instead of using Google Cloud Build in the cloud. Once compiled, the Firebase +CLI packages the pre-built standalone assets and uploads them directly to Cloud +Run. + +This feature is highly useful for faster deployments, bypassing cloud build +queue times, and debugging build outputs locally. + +> [!WARNING] This is an early preview of prototype code and you are likely to +> encounter bugs. Do NOT use this with production backends or sensitive data. +> Only use test backends and non-sensitive test data as you evaluate this +> feature. + +______________________________________________________________________ + +## Mandatory Rules for Coding Agents + +> [!CAUTION] **CRITICAL SECURITY INSTRUCTION FOR CODING AGENTS (AI +> ASSISTANTS):** +> +> 1. **DO NOT** run local builds with the `--allow-local-build-secrets` flag +> unless the developer has explicitly instructed you to bypass confirmations +> for build secrets. +> 1. **PAUSE AND WARN** the user if you detect any `BUILD`-available secrets in +> `apphosting.yaml`. You must explain that: +> - Local builds will download the raw, unencrypted secret values from Google +> Cloud Secret Manager to your local machine. +> - These raw secret values can easily be permanently baked into your +> client-side JavaScript bundles (e.g. due to Next.js bundler behavior) or +> left behind in local build artifacts/temporary files. +> 1. **GET EXPLICIT APPROVAL** from the user before proceeding with a local +> build when secrets are configured. + +______________________________________________________________________ + +## Setup and Configuration + +### 1. Enable Experiment + +Enable the experimental CLI preview flag on your local machine: + +```bash +npx -y firebase-tools@latest experiments:enable apphostinglocalbuilds +``` + +### 2. Configure `firebase.json` + +To instruct the Firebase CLI to perform a local build during deploy, set +`"localBuild": true` in the `apphosting` block of your `firebase.json`: + +```json +{ + "apphosting": [ + { + "backendId": "my-local-build-backend", + "localBuild": true, + "rootDir": "/", + "ignore": [ + "node_modules", + ".git", + "firebase-debug.log", + "firebase-debug.*.log", + "functions" + ] + } + ] +} +``` + +______________________________________________________________________ + +## Technical Details (How It Works Under the Hood) + +When you execute `npx -y firebase-tools@latest deploy --only apphosting`, the +local build flow performs the following steps: + +1. **Isolated Scratch Workspace**: The CLI creates a temporary scratch folder + named `.local_build_` in your project root and copies all project + files into it. It applies your `firebase.json` ignore patterns and respects + `.gitignore` to ensure a clean build context matching what would have been + sent to Cloud Build. +1. **Secret Injection**: If your `apphosting.yaml` environment contains secrets + marked for `BUILD` availability: + - In interactive mode, the CLI will prompt you with a warning before + downloading. + - In non-interactive mode (e.g. CI scripts), the deployment will abort with + an error unless the `--allow-local-build-secrets` flag is provided. + - The CLI programmatically fetches the raw values from GCP Secret Manager and + injects them into the local build process's `process.env`. +1. **Universal Maker Execution**: The CLI downloads the architecture-aware + **Universal Maker** build engine binary (caching it at + `~/.cache/firebase/universal-maker/`), verifies its size and SHA256 checksum, + and executes it in the scratch folder to compile the application. +1. **Output Extraction**: The CLI parses the generated `build_output.json` and + `.apphosting/bundle.yaml` to extract the application's start-up `runCommand` + and stand-alone output files (e.g., `.next/standalone`). +1. **Tarball Compacting & GCS Upload**: The standalone output folder and + configurations are compressed into an optimized `.tar.gz` tarball (ignoring + unneeded source or `node_modules`), uploaded to GCS, and the + `.local_build_` directory is safely deleted. +1. **Rollout Deployment**: The App Hosting API is invoked with a `locallyBuilt` + source payload containing the storage URL, start-up `runCommand`, and + discovered environment variables. + +______________________________________________________________________ + +## All Limitations & Warnings + +Before adopting local builds, you must be aware of the following strict +limitations: + +### 1. Host Platform Restrictions + +The pre-compiled Universal Maker build binary only supports a subset of +operating systems and architectures: + +- **macOS**: Only macOS Apple Silicon (`darwin_arm64`) is supported. macOS Intel + (`darwin_x64`) is not supported. +- **Linux**: Only Linux x86-64 (`linux_x64`) is supported. Linux ARM + (`linux_arm64`) is not supported. +- **Windows**: Windows (`win32`) is not supported. Windows developers must + either deploy from source (using Cloud Build) or run the CLI inside a WSL + (Windows Subsystem for Linux) environment to perform local builds. + +### 2. Security & Secret Exposure Caveats + +If your build depends on secrets marked for `BUILD` availability, the CLI +fetches the raw, unencrypted values from Cloud Secret Manager and sets them as +environment variables in the build context. + +- **General Build-Time Risk**: Developers must be extremely cautious when using + build-available secrets. Ensure your application code and build scripts do not + accidentally expose or embed these sensitive values into client-side bundles, + compiled files, or public assets. This risk is universal and is equally + critical whether you compile locally or remotely on Google Cloud Build. + +### 3. Local Directory Collisions & Artifact Leftovers + +The local build pipeline creates intermediate workspace directories (such as +`.local_build_`) during the compilation process. + +- **Interrupted Cleanup**: While the CLI is designed to automatically delete + these intermediate folders upon a successful build, **if the build process is + interrupted, force-quit, or crashes mid-execution, these artifacts may be left + on your system**. You will need to manually delete these leftover directories + to secure any cached environment variables and to prevent subsequent + `firebase deploy` commands from blocking due to directory collisions. diff --git a/skills/firebase-app-hosting-basics/references/runtimes_and_abiu.md b/skills/firebase-app-hosting-basics/references/runtimes_and_abiu.md new file mode 100644 index 00000000..2a57c14d --- /dev/null +++ b/skills/firebase-app-hosting-basics/references/runtimes_and_abiu.md @@ -0,0 +1,51 @@ +# App Hosting Runtimes & Automatic Base Image Updates (ABIU) + +Firebase App Hosting allows you to choose a specific runtime environment (e.g., +versioned Node.js) for your backend. When you choose a versioned runtime, +**Automatic Base Image Updates (ABIU)** automatically applies security patches +to your underlying OS/runtime container without requiring you to rebuild or +redeploy. + +______________________________________________________________________ + +## Mandatory Rules for Coding Agents + +> [!IMPORTANT] **CRITICAL RUNTIME COMPATIBILITY INSTRUCTION FOR CODING AGENTS +> (AI ASSISTANTS):** +> +> 1. **Inspect package.json first**: Before recommending a runtime version or +> running backend creation commands, you **MUST** read the user's +> `package.json` file and inspect the `engines.node` field (e.g., if +> `"engines": { "node": ">=22.0.0" }` is specified, you must select +> `nodejs22` or `nodejs24`). +> 1. **Prevent mismatch failures**: Creating a backend with a runtime version +> that is incompatible with the `engines` field will trigger a build failure +> during the Cloud Build phase. +> 1. **Warn on default runtime**: If the default unversioned `nodejs` runtime is +> used, warn the developer that ABIU is completely disabled (leaving their +> container without automated security updates) and recommend migrating to a +> versioned runtime (e.g. `nodejs22`). + +______________________________________________________________________ + +## Specifying Runtime During Backend Creation + +When creating a new backend programmatically or in non-interactive environments, +specify the target versioned runtime using the `--runtime` flag: + +```bash +npx -y firebase-tools@latest apphosting:backends:create --runtime nodejs22 --backend my-backend-name --primary-region us-central1 +``` + +______________________________________________________________________ + +## Runtime Lifecycles & Support + +Runtimes progress through the following lifecycle phases (mirroring Cloud Run's +support): + +| Lifecycle State | Description | Agent Actions | +| :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | +| **Supported** | Fully supported. ABIU security patches are active. | Recommend these versions to users. | +| **Deprecated** | Approaching end of support. Existing apps continue running, but warnings appear in the Console. | Warn the user to migrate to a newer version as soon as possible. | +| **Decommissioned** | Completely unsupported. New builds or backends using this version will fail with errors. Existing containers may stop working or be deleted. | **NEVER** allow creation of new backends on decommissioned versions. Assist the user in upgrading. |