Deploy

One command deploys Arc CMS to a Firebase project: it asks which project and what to deploy, builds what is needed, and checks the result. Scripts and CI pass the same choices as flags.

Deploying a new project for the first time is covered in Deploy for the first time. To send just one function or just the rules, see Deploy only what changed.

Deploy with the guided deploy

Run it in a terminal and answer the questions. Each has a default in brackets; press Enter to take it.

npm run deploy

1. Which Firebase project? The aliases in .firebaserc, plus the project chosen with firebase use. The default is the project you deployed to last from this checkout. "Another project id" takes any other.

2. Its settings. The deploy prints the database, website, storage bucket, app users and functions region the project uses, and, for a project with its own web settings, whether its website builds like production or in development mode (see Build like production). They come from arccms.config.json, and the files generated from it are rebuilt on every deploy, so they are never stale. A project with no settings yet is offered a short setup, the same as npm run arc:configure (see Configure a project).

3. What to deploy? See the table below. A choice whose files changed since its last deploy is marked "(changed since the last deploy)".

4. Confirm. The summary shows the project, the Firebase config file and the exact command. For a production project (one marked --production=yes, the alias production, or an id with prod, production or live as a part of it) you type the project id instead of pressing Enter.

The choices, remembered per project in .arc-deploy-state.json (not committed), are the defaults next time.

What each choice deploys

The website is offered for every project that has one (not for a project set up with --site=none). A deploy always builds what it deploys: the website is built for the project being deployed to, with that project's Firebase web settings, so a site can never go out talking to another project. Which settings that is, and how to add a project such as staging, is on Dev, staging and production.

Deploy from a script or CI

With any option, npm run deploy skips the guided questions and passes the options on to firebase deploy. The questions it can still ask, in a terminal, are before it deletes functions (see Functions that are deleted), the id of a project marked production, and, once per project, whether to set up phone sign-in's Google Cloud setting. Off a terminal it asks nothing: what would need an answer takes a flag instead. For a whole CI job, see Deploy from CI. Off a terminal and with no options, it prints these examples and stops.

npm run deploy -- --only functions:arccms --project default
npm run deploy -- --only functions:arccms:arccms.<name> --project default
npm run deploy -- --only firestore --project default
npm run deploy -- --only storage --project default
npm run deploy -- --only hosting --project default

Copy these as they are, except for the project. arccms in functions:arccms is not a project or database name: it is the name of the Arc CMS functions codebase in firebase.json, the same in every install, and the arccms- in front of every function name. The part that differs from person to person is --project: an alias from your own .firebaserc (default, production) or a project id.

Either way, the deploy also:

• builds the functions (npm run build --prefix functions) before any deploy that includes them;
• waits 65 seconds and deploys again, up to two times, any function the Firebase CLI started but never reported as done (Google limits how many functions can change per minute). When the error says Google is still setting up Eventarc, as on a project's first deploy, it waits 5 minutes instead (see A first deploy to a new project);
• when a deploy that includes the website fails before the website step, does not deploy the website, says so and prints the commands that deploy it alone and publish its pages;
• fails when a function still never reported success, and prints the command that redeploys it;
• stops with a plain message when you ask for hosting on a project with no website, or for storage rules on a bucket shared with another app;
• records a whole deploy of a part (all functions, firestore, storage, hosting) for the guided deploy's "only what changed";
• with the sms feature on, checks once per project, with gcloud, that phone sign-in can sign people in (the IAM Service Account Credentials API and the Token Creator role for the functions' service account), and in a terminal offers to set up what is missing. A yes or a no is remembered in .arc-deploy-state.json; without gcloud it says so once. It never stops the deploy. See Google Cloud setup for phone sign-in.

deploy:dev and deploy:prod

Two scripts deploy everything to the default or production alias in one go:

npm run deploy:dev
npm run deploy:prod

Each runs the deploy with --project <alias> --non-interactive --force and no --only, which builds the website for that project and the functions first, then publishes the static pages (npm run seed:dev or npm run seed:prod). For any other project, use npm run deploy -- --project <alias>, then npm run seed -- <alias>.

When the production project is marked production, deploy:prod asks for its id in a terminal, and anywhere else stops before it deploys. From a script, run the deploy with the id instead, then the seed: npm run deploy -- --project production --confirm-production=<project id> --non-interactive --force and npm run seed:prod.

Pages left open across a deploy

A website deploy replaces the hashed code files on Hosting. A visitor whose page was open before it keeps the old version until the page loads again. When they open a screen the old page had not loaded yet, its code file is gone: Arc CMS then loads that address afresh, so they land on it in the new version. An installed app offers its update instead (see Open screens offline and after a deploy).

Regions

Every database read or write a function makes travels to the database and back. Functions far from their database are slow: with the database in Mumbai (asia-south1) and the functions in Iowa (us-central1, the Firebase default), one sign-in step takes several seconds. So the functions run next to the database, in the region set by functionsRegion (see Config keys).

Before every deploy that includes functions, the deploy compares the two. It looks up the database's location once per project and remembers it in .arc-deploy-state.json.

• No Arc CMS function deployed yet: the deploy sets functionsRegion to the database's region, says so, and deploys there. A website in the same deploy is built after this, so it calls the functions in their new region. The region is saved in arccms.config.json, which git ignores, and in src/environments/arc-install.ts: commit that one, the website reads it. Where arccms.config.json is recreated, as in CI, pass --functions-region to arc:configure from then on (see Deploy from CI).
• Functions already deployed somewhere else: the deploy warns and deploys anyway. It never moves live functions. The guided deploy asks once whether to keep warning for that project.

A database in a multi-region location counts as next to the functions in one of its regions: nam5 with us-central1, eur3 with europe-west1. A location with no functions of its own gets the nearest region that has them.

The region reaches three places, all written by npm run arc:configure: the functions (ARC_FUNCTIONS_REGION), the website, which calls them there (arc-install.ts), and the Hosting rewrites to the unsubscribe and preference functions (firebase.<projectId>.json). To choose it yourself, before the first deploy:

npm run arc:configure -- --project=default --functions-region=asia-south1

A region costs a little more or less than another per call, but at the free allowance most sites stay inside, the difference is nothing, and functions next to the database also stop the paid traffic between regions.

A first deploy to a new project

The first deploy of functions to a project turns on the Google Cloud services they need, without asking: Cloud Functions, Cloud Build, Artifact Registry, Cloud Run, Eventarc, Pub/Sub, Cloud Storage, Cloud Scheduler (for the scheduled functions) and, for a deploy of everything, Firebase Extensions. The project must be on the Blaze plan. Turning a service on costs nothing; you pay for what the functions use, and Artifact Registry stores each function's built image. The account that deploys needs permission to turn services on (Owner, Editor or Service Usage Admin).

Two failures are normal on that first deploy, and the deploy's own retry clears them:

• The Firestore triggers fail with "Permission denied while using the Eventarc Service Agent" and "Retry the deployment in a few minutes": Google is still giving Eventarc, which delivers the database events, its permissions. The deploy waits 5 minutes and deploys just those, twice at most. If they still fail, it says so: wait a few minutes and run the same deploy again.
• onSignInDeleted, the one first generation function, can fail with "Build failed: Build error details not available". Its build looked for the project's image repository (gcf-artifacts) a few seconds before Cloud Functions created it for the other functions. The retry a minute later builds it.

Neither needs a setting changed. When the functions fail, the website is not deployed in the same run; the deploy says so and prints how to deploy it alone.

Functions that are deleted

A deploy of all the functions (--only functions, --only functions:arccms, or no --only) makes the project match the build, so it deletes the Arc CMS functions the build no longer has: those of a feature turned off in src/custom/features.ts, a search collection removed from functions/src/custom/search-sources.ts, or a function that was renamed.

• Before deploying, it lists them and asks once. The guided deploy asks on its own prompt.
• Off a terminal it needs --yes (or --force). Without it, it stops and deploys nothing.
• If the Firebase CLI skips a delete (it does when another function fails), the deploy deletes it afterwards.
• A deploy of named functions (--only functions:arccms:arccms.<name>) never deletes anything.
• Only the arccms codebase is compared, so another app's functions in the same project are never touched.

npm run deploy -- --only functions:arccms --project default --yes

A deleted function's URL stops working, for example a payment webhook registered with the payment provider or a link in an email already sent.

When the order matters

"Everything", deploy:dev and deploy:prod run one firebase deploy, and the Firebase CLI decides the order of the parts. That is fine for most changes. When a change tightens a security rule so that the browser must go through a new function, or stops the browser reading something older website code still reads, deploy in steps instead, so nothing is refused in between:

1. The functions, so the new ones exist.

2. The indexes (npm run deploy -- --only firestore:indexes --project <alias>). Indexes build in the background: wait until the Firebase console shows them enabled.

3. The website, so no page still does what the new rules refuse.

4. The rules, last (npm run deploy -- --only firestore:rules --project <alias>, and storage if they changed).

If the rules go out first, the refused reads and writes fail at once. To recover, deploy the previous rules again from git.

After the deploy

Check the callables

Firebase lets the browser call a callable function when it creates it. If that step is missed, for example in a partly failed deploy, every browser call to it fails with HTTP 403, and later deploys do not repair it. The guided deploy checks every callable it just created. With flags, add --probe, or run the check yourself after a deploy that adds a callable and before a release:

bash functions/scripts/check-callable-access.sh

It checks the project a deploy would go to (the firebase use project, else the default alias) in that project's functions region, and says which as it starts. Set FIREBASE_PROJECT=<alias or id> or FIREBASE_REGION to check another. It reads the callables from the functions build (plus the app's list in functions/src/custom/public-callables.txt), so build the functions first; GCLOUD_PROJECT is not needed. Give function names after the script to check only those, without the arccms- prefix (custom-<name> for an app's own).

Publish the pages again

Published pages are static files that Cloud Functions write to Hosting; none of them is in the build. Every website deploy through npm run deploy keeps them: it uploads the build to a preview channel named arc-deploy first, then releases one live version holding the build and every published page, so visitors and search engines never see a page drop out. With the seo feature off, it leaves out robots.txt, the sitemap, llms.txt, llms-full.txt, the IndexNow key file and the feeds, so one website deploy removes the ones an earlier publish wrote. Every other part (functions, rules, indexes) goes through firebase deploy as before.

Kept pages still show the old templates, header and footer, so after a website deploy every page is published again from the new files. Who does that:

To publish every page again from a terminal:

npm run seed:dev
npm run seed:prod
npm run seed -- staging

seed:dev publishes to the default alias, seed:prod always to production, and npm run seed -- <alias or id> to any project. It republishes the home page in every language, every published content page and list page, every static page the site has, robots.txt, llms.txt, the sitemap and the RSS feeds. It runs on your machine with your Firebase CLI login (run firebase login first), not through a Cloud Function, and does nothing for a project with no website. The seedStaticPages callable does the same from the browser, for admins only.

When the deploy stops

More problems and their fixes are in Troubleshooting.