Initial commit
This commit is contained in:
St. Nebula
@@ -0,0 +1,58 @@
|
||||
---
|
||||
name: firebase-app-hosting-basics
|
||||
description: Deploy and manage web apps with Firebase App Hosting. Use this skill when deploying Next.js/Angular apps with backends.
|
||||
---
|
||||
|
||||
# App Hosting Basics
|
||||
|
||||
## Description
|
||||
This skill enables the agent to deploy and manage modern, full-stack web applications (Next.js, Angular, etc.) using Firebase App Hosting.
|
||||
|
||||
**Important**: In order to use App Hosting, your Firebase project must be on the Blaze pricing plan. Direct the user to https://console.firebase.google.com/project/_/overview?purchaseBillingPlan=metered to upgrade their plan.
|
||||
|
||||
## Hosting vs App Hosting
|
||||
|
||||
**Choose Firebase Hosting if:**
|
||||
- You are deploying a static site (HTML/CSS/JS).
|
||||
- You are deploying a simple SPA (React, Vue, etc. without SSR).
|
||||
- You want full control over the build and deploy process via CLI.
|
||||
|
||||
**Choose Firebase App Hosting if:**
|
||||
- You are using a supported full-stack framework like Next.js or Angular.
|
||||
- You need Server-Side Rendering (SSR) or ISR.
|
||||
- You want an automated "git push to deploy" workflow with zero configuration.
|
||||
|
||||
## Deploying to App Hosting
|
||||
|
||||
### Deploy from Source
|
||||
|
||||
This is the recommended flow for most users.
|
||||
1. Configure `firebase.json` with an `apphosting` block.
|
||||
```json
|
||||
{
|
||||
"apphosting": {
|
||||
"backendId": "my-app-id",
|
||||
"rootDir": "/",
|
||||
"ignore": [
|
||||
"node_modules",
|
||||
".git",
|
||||
"firebase-debug.log",
|
||||
"firebase-debug.*.log",
|
||||
"functions"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
2. Create or edit `apphosting.yaml`- see [Configuration](references/configuration.md) for more information on how to do so.
|
||||
3. 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.
|
||||
4. Run `npx -y firebase-tools@latest deploy` when you are ready to deploy.
|
||||
|
||||
### Automated deployment via GitHub (CI/CD)
|
||||
|
||||
Alternatively, set up a backend connected to a GitHub repository for automated deployments "git push" deployments.
|
||||
This is only recommended for more advanced 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.
|
||||
|
||||
## Emulation
|
||||
|
||||
See [Emulation](references/emulation.md) for more information on how to test your app locally using the Firebase Local Emulator Suite.
|
||||
@@ -0,0 +1,71 @@
|
||||
# App Hosting CLI Commands
|
||||
|
||||
The Firebase CLI provides a comprehensive suite of commands to manage App Hosting resources. These commands are often faster and more scriptable than using the Firebase Console.
|
||||
|
||||
## Initialization
|
||||
|
||||
### `npx -y firebase-tools@latest init apphosting`
|
||||
|
||||
- **Purpose**: Interactive command that sets up App Hosting in your local project.
|
||||
Use this command only if you are able to handle interactive CLI inputs well.
|
||||
Alternatively, you can manually edit `firebase.json` and `apphosting.yml`.
|
||||
|
||||
- **Effect**:
|
||||
- Detects your web framework.
|
||||
- Creates/updates `apphosting.yaml`.
|
||||
- Can optionally create a backend if one doesn't exist.
|
||||
|
||||
## Backend Management
|
||||
|
||||
### `npx -y firebase-tools@latest apphosting:backends:list`
|
||||
|
||||
- **Purpose**: Lists all backends in the current project.
|
||||
|
||||
### `npx -y firebase-tools@latest apphosting:backends:get <backend-id>`
|
||||
|
||||
- **Purpose**: Shows details for a specific backend.
|
||||
|
||||
### `npx -y firebase-tools@latest apphosting:backends:delete <backend-id>`
|
||||
|
||||
- **Purpose**: Deletes a backend and its associated resources.
|
||||
|
||||
### `npx -y firebase-tools@latest apphosting:rollouts:list <backend-id>`
|
||||
|
||||
- **Purpose**: Lists the history of rollouts for a backend.
|
||||
|
||||
## Secrets Management
|
||||
|
||||
App Hosting uses Cloud Secret Manager to securely handle sensitive environment variables (like API keys).
|
||||
|
||||
### `npx -y firebase-tools@latest apphosting:secrets:set <secret-name>`
|
||||
|
||||
- **Purpose**: Creates or updates a secret in Cloud Secret Manager and makes it available to App Hosting.
|
||||
- **Behavior**: Prompts for the secret value (hidden input).
|
||||
|
||||
### `npx -y firebase-tools@latest apphosting:secrets:grantaccess <secret-name>`
|
||||
|
||||
- **Purpose**: Grants the App Hosting service account permission to access the secret.
|
||||
- **Note**: Often handled automatically by `secrets:set`, but useful for debugging permission issues or granting access to existing secrets.
|
||||
|
||||
## Automated deployment via GitHub (CI/CD)
|
||||
|
||||
**IMPORTANT** Only use these commands if you are setting up automated deployments via GitHub. If you are managing deployments using `npx -y firebase-tools@latest deploy`, DO NOT use these commands.
|
||||
|
||||
### `npx -y firebase-tools@latest apphosting:rollouts:create <backend-id>`
|
||||
|
||||
- **Purpose**: Manually triggers a new rollout (deployment).
|
||||
- **Options**:
|
||||
- `--git-branch <branch>`: Deploy the latest commit from a specific branch.
|
||||
- `--git-commit <commit-hash>`: Deploy a specific commit.
|
||||
- **Use Case**: Useful for redeploying without code changes, or rolling back to a specific commit.
|
||||
|
||||
### `npx -y firebase-tools@latest apphosting:backends:create`
|
||||
|
||||
- **Purpose**: Creates a new App Hosting backend. Use this when setting up automated deployments via GitHub.
|
||||
- **Options**:
|
||||
- `--app <webAppId>`: The ID of an existing Firebase web app to associate with the backend.
|
||||
- `--backend <backendId>`: The ID of the new backend.
|
||||
- `--primary-region <location>`: The primary region for the backend.
|
||||
- `--root-dir <rootDir>`: The root directory for the backend. If omitted, defaults to the root directory of the project.
|
||||
- `--service-account <service-account>`: The service account used to run the server. If omitted, defaults to the default service account.
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
# App Hosting Configuration (`apphosting.yaml`)
|
||||
|
||||
The `apphosting.yaml` file is the source of truth for your backend's configuration. It must be located in the root of your app's directory (or the specific root directory if using a monorepo).
|
||||
|
||||
## File Structure
|
||||
|
||||
```yaml
|
||||
# apphosting.yaml
|
||||
|
||||
# Cloud Run service configuration
|
||||
runConfig:
|
||||
cpu: 1
|
||||
memoryMiB: 512
|
||||
minInstances: 0
|
||||
maxInstances: 100
|
||||
concurrency: 80
|
||||
|
||||
# Environment variables
|
||||
env:
|
||||
- variable: STORAGE_BUCKET
|
||||
value: mybucket.app
|
||||
availability:
|
||||
- BUILD
|
||||
- RUNTIME
|
||||
- variable: API_KEY
|
||||
secret: myApiKeySecret
|
||||
```
|
||||
|
||||
## `runConfig`
|
||||
Controls the resources allocated to the Cloud Run service that serves your app.
|
||||
- `cpu`: Number of vCPUs. Note: If `< 1`, concurrency MUST be set to `1`.
|
||||
- `memoryMiB`: RAM in MiB (128 to 32768).
|
||||
- `minInstances`: Minimum containers to keep warm (default 0). Set to >= 1 to avoid cold starts.
|
||||
- `maxInstances`: Maximum scaling limit (default 100).
|
||||
- `concurrency`: Max concurrent requests per instance (default 80).
|
||||
|
||||
### Resource Constraints
|
||||
- **CPU vs Memory**: Higher memory often requires higher CPU.
|
||||
- > 4GiB RAM -> Needs >= 2 vCPU
|
||||
- > 8GiB RAM -> Needs >= 4 vCPU
|
||||
|
||||
## `env` (Environment Variables)
|
||||
Defines environment variables available during build and/or runtime.
|
||||
|
||||
- `variable`: The name of the env var (e.g., `NEXT_PUBLIC_API_URL`).
|
||||
- `value`: A literal string value.
|
||||
- `secret`: The name of a secret in Cloud Secret Manager. use `npx -y firebase-tools@latest apphosting:secrets:set` to create these.
|
||||
- `availability`: Where the variable is needed.
|
||||
- `BUILD`: Available during the `npm run build` process.
|
||||
- `RUNTIME`: Available when the app is serving requests.
|
||||
- Defaults to both if not specified.
|
||||
@@ -0,0 +1,47 @@
|
||||
# App Hosting Emulation
|
||||
|
||||
You can test your App Hosting setup locally using the Firebase Local Emulator Suite. This allows you to verify your app's behavior with environment variables and secrets before deploying.
|
||||
|
||||
## Configuration: `apphosting.emulator.yaml`
|
||||
This optional file overrides `apphosting.yaml` settings specifically for the local emulator. Use it to provide local secret values or override resource configs. If it contains sensitive values such as API keys, do not commit it to source control.
|
||||
|
||||
```yaml
|
||||
# apphosting.emulator.yaml (gitignored usually)
|
||||
runConfig:
|
||||
cpu: 1
|
||||
memoryMiB: 512
|
||||
|
||||
env:
|
||||
- variable: API_KEY
|
||||
value: "local-dev-api-key" # Override secret with local value
|
||||
```
|
||||
|
||||
## Running the Emulator
|
||||
To start the App Hosting emulator:
|
||||
|
||||
```bash
|
||||
npx -y firebase-tools@latest emulators:start --only apphosting
|
||||
```
|
||||
|
||||
Or, if you are also using other emulators (Auth, Firestore, etc.):
|
||||
|
||||
```bash
|
||||
npx -y firebase-tools@latest emulators:start
|
||||
```
|
||||
|
||||
## Capabilities
|
||||
- **Builds your app**: Runs the build command defined in your `package.json` to generate the serving artifact.
|
||||
- **Serves locally**: Runs the app on `localhost:5004` (default).
|
||||
Configurable by setting `host` and `port` in the `emulators` block of `firebase.json`, like so:
|
||||
|
||||
```json
|
||||
{
|
||||
"emulators": {
|
||||
"apphosting": {
|
||||
"host": "localhost",
|
||||
"port": 5004
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
- **Env Var Injection**: Injects variables defined in `apphosting.yaml` and `apphosting.emulator.yaml` into the process.
|
||||
Reference in New Issue
Block a user