Share a Firebase project

Install Arc CMS in a Firebase project that another app already uses, as that app's admin, email and marketing backend, without touching the other app's data, rules, functions or website.

Why it is built this way is in Sharing a Firebase project. A project of its own needs none of this: see Configure a project.

What must not collide

Shared by the project	How Arc CMS keeps apart	How to check
Firestore	Its own named database, usually `arccms`, with its own rules, indexes and triggers	`ARC_DATABASE_ID` in `functions/.env.{projectId}`, and `"database"` in `firebase.{projectId}.json`
Cloud Functions	Every function is named `arccms-` plus its name, in the `arccms` codebase, so an Arc CMS deploy never deletes the other app's functions, and theirs never delete Arc CMS's	`firebase functions:list`: every Arc CMS function starts with `arccms-`
Hosting	A hosting site of its own, or none (`--site=none`) when Arc CMS is only an admin backend	`"hosting"` in the generated config names your site, or is absent
Storage	A bucket of its own: a bucket has one rules file, and deploying Arc CMS's would replace the other app's	`"storage"` in the generated config names your bucket
Sign-in accounts	Shared. Sign-ups are off once the first admin exists, so the other app's users cannot sign in to Arc CMS	Signing in with one of the other app's users ends in "no access"
Custom claims	Arc CMS uses only `arccms_role` and `arccms_uid`, and merges them with other claims	The other app merges its own claims too (below)
Deploy settings	Arc CMS's settings all start with `ARC_`	Nothing to do

Install next to the other app

Find the other app's database location, in the Firebase console under Firestore, or with:
```
firebase firestore:databases:list
```
Arc CMS's database goes in the same location.
Answer the setup questions. Run the guided deploy in a terminal:
```
npm run deploy
```
The first time it meets a project with no Arc CMS settings, it asks how the project is used. Choose "Shared with another app", then accept or change the suggested names: the database (arccms), a website of its own or none, the bucket and the upload folder in it, and where the other app keeps its users (or none). It writes the settings, prints the commands that create the resources, and stops.

Without the questions: pass the same choices as flags, and check them first with --dry-run:
```
npm run arc:configure -- --project=default --profile=backend --database=arccms --site=YOUR_SITE --bucket=YOUR_BUCKET --prefix=arccms/ --region=YOUR_LOCATION --dry-run
```
Create the resources with the printed commands, if the database, site or bucket does not exist yet. Nothing creates them for you:
```
firebase firestore:databases:create arccms --location=YOUR_LOCATION
firebase hosting:sites:create YOUR_SITE
gcloud storage buckets create gs://YOUR_BUCKET --location=YOUR_LOCATION
```
Then link the bucket to Firebase: in the console, Storage, the bucket menu, "Import existing Google Cloud Storage buckets".
Commit src/environments/arc-install.ts. The website reads its database, bucket and upload folder from it.
Deploy with npm run deploy again, and pick what to deploy. It uses the generated firebase.{projectId}.json; a plain firebase deploy does not, and would deploy Arc CMS's rules and website over the other app's. See Deploy.
Create the first admin in the onboarding wizard (Create the first admin). When it finishes, sign-ups turn off: Settings, User Settings, "Enable User Signups" is off, and every sign-up path refuses new accounts.
Add more admins under Users, Add User. If the address already has a login in the other app, that login is reused and keeps its own password; the record is marked as shared, so deleting the person from Arc CMS never deletes their login to the other app, and Edit does not offer to change its password.

Do not run firebase deploy --dry-run to "check" the configuration. With a named database in the config, even a dry run creates the missing database, in the project's default location, which cannot be changed afterwards. Create the database yourself first, with the location you chose.

The configuration files

One checkout can deploy to several projects (development, production), each set up differently. arccms.config.json holds the choices: keys at the top apply to every project, and projects.<projectId> overrides them for one project. arccms.config.example.json shows the shape:

{
  "profile": "standalone",
  "projects": {
    "your-project-id": {
      "profile": "backend",
      "databaseId": "arccms",
      "hostingSite": "your-project-arccms",
      "storageBucket": "your-project-arccms",
      "storagePrefix": ""
    }
  }
}

npm run arc:configure reads it, with its flags written into the entry for --project first, and writes:

File	Commit it?	Holds
`arccms.config.json`	No	Your choices, per project
`src/environments/arc-install.ts`	Yes	Each project's database, bucket, upload folder, admin-only sign-in, offline cache and analytics consent, for the website. The build uses the entry for its own Firebase project.
`functions/.env.{projectId}`	No	`ARC_DATABASE_ID`, `ARC_HOSTING_SITE`, `ARC_STORAGE_BUCKET`, `ARC_STORAGE_PREFIX` and the app audience settings, for the functions
`firebase.{projectId}.json`	No	The Firebase CLI config with the named database, bucket and site. Removed again when a project uses none of them.

Flag	Sets
`--profile=standalone\|backend`	A project of its own, or a backend in a shared project. A backend refuses to run without its own database (not `(default)`), a hosting site (or `none`) and a bucket, and turns on admin-only sign-in.
`--database=`	The Firestore database id
`--site=`	The hosting site, or `none`
`--bucket=`	The Storage bucket
`--prefix=`	An upload folder for every Arc CMS file, such as `arccms/`: one folder, ending in a slash
`--region=`	The location used in the printed create commands
`--admin-only-sign-in=yes\|no`	Whether onboarding turns sign-ups off (yes by default for a backend)
`--app-users-database=`, `--app-users-path=`, `--app-users=own`	The other app's users as an audience: Connect your app's users
`--dry-run`	Print the changes, write nothing

An install with its own database but no bucket of its own shares the project's default bucket with the other app. Its storage rules are then not deployed at all, so the other app's are not replaced, and arc:configure says so. Give Arc CMS its own bucket with --bucket to deploy them.

What the other app must know

Merge custom claims, never replace them. Setting claims with only its own keys removes arccms_role and arccms_uid, and an Arc CMS admin loses access until the Arc CMS app puts them back. See Follow the account contract.
Do not use a claim named arccms_ anything. Its own role claim is fine: Arc CMS never reads it.
Never write to the Arc CMS database. To read Arc CMS data from the other app, open the named database, such as getFirestore(app, 'arccms').
Its users stay its own. To email or segment them from Arc CMS, see Connect your app's users.

More traps, such as a database that was deleted and created again, are in Sharing a Firebase project.