Configure a project

Connect your copy of Arc CMS to a Firebase project in three moves: create the project, give it the Firebase CLI alias default, and fetch its web settings. Do this before the first npm run dev: a fresh copy names no project, and stops until it has one. A project that Arc CMS has to itself needs nothing more; one shared with another app also runs npm run arc:configure.

Create the Firebase project

1. In the Firebase console, add a project (or open one you have) and move it to the Blaze plan. Cloud Functions do not deploy without it.

2. Firestore Database: create the database in production mode, in the region nearest your visitors. Arc CMS deploys its own security rules, and its first deploy puts the functions in the same region (see Regions). For a project shared with another app, skip this step: Arc CMS gets a database of its own (see Install profiles).

3. Authentication: click Get started and turn on the Email/Password provider. The first admin signs up with it.

4. Storage: click Get started. Arc CMS deploys its own storage rules.

5. Project settings, General, Your apps: add a Web app. The next step fetches its settings for you.

Point the code at the project

1. Tell the Firebase CLI which project to use. Give your development project the alias default:

   firebase use --add

   This writes .firebaserc, which git ignores. Add your live project the same way with the alias production when you have one.

2. Fetch the project's web settings:

   npm run arc:configure -- --project=default --web-config=fetch

   This writes src/environments/firebase-web.<projectId>.ts; commit it. From then on npm run dev and npm run build use the default alias's project and print it as they start: Firebase project: <id> (the default alias, ...). Do the same for each other project (see Dev, staging and production).

The environment files

The app reads its own entry in arc-install.ts by the projectId in its firebaseConfig, so one build can hold settings for several projects. A project with no entry there uses the one its firebase-web.<projectId>.ts carries. These files are yours: Arc CMS never changes their values in an update (see Upgrade Arc CMS).

Install profiles

The profile says whether Arc CMS has the Firebase project to itself or shares it with another app.

For the reasons behind the backend rules (why the other app's database, rules and bucket are left alone), see Sharing a Firebase project.

Run arc:configure

Recommended: let the first npm run deploy do it. For a project with no settings it asks how the project is used (only by Arc CMS, or shared with another app), asks for the names it needs, and runs arc:configure for you (see Deploy for the first time). A standalone project that keeps every default needs no settings at all.

Alternative: run it yourself, with flags that set the project's entry in the config file. For example, a backend install on the default project:

npm run arc:configure -- --project=default --profile=backend --database=arccms --site=YOUR_PROJECT-arccms --bucket=YOUR_PROJECT-arccms --prefix=arccms/

To see what would change without writing anything:

npm run arc:configure -- --project=default --dry-run

What it does, step by step

1. Finds the project: --project takes an alias from .firebaserc or a project id; without it, the default alias. With neither, it stops.

2. If you passed flags, merges them into projects.<projectId> in arccms.config.json, creating the file if needed.

3. Works out the project's settings: the top-level keys, overridden by the project's own entry, with blanks dropped and the defaults filled in.

4. Checks them, and stops with a message for each problem: an unknown profile, a backend without its own database, site or bucket, a bad database id or upload folder.

5. Writes the generated files (below), each only when its content changes, and lists what it created, updated or removed.

6. For a backend profile, prints the commands that create the database, hosting site and bucket. It never creates cloud resources itself.

The config file

arccms.config.json sits at the repository root and is ignored by git: it belongs to the checkout, like .firebaserc. arccms.config.example.json shows the shape. Top-level keys apply to every project; projects.<projectId> overrides them for one project. With no file, every project uses the defaults.

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

Every value is a string.

The three App audience keys are explained on App audience.

What gets generated

The committed functions/.env holds the defaults every project starts from. The guided npm run deploy (run with no options) runs arc:configure again before each deploy of a configured project, so the generated files never go stale.

Next

Deploy for the first time: the local app calls the deployed functions and needs the deployed rules. Then Run it locally. Every key and generated value is also listed in Configuration keys.