deploy.md

title	Deploying ConvoArena
layout	default

Backend deployment

You need a Firebase project with Authentication, Firestore, Realtime Database, Storage and Functions enabled, and its ID set in .firebaserc. If you don't have one yet, start with Create a Firebase project.

Then, using the Firebase CLI, run:

npx firebase login  # If not already logged in
npx firebase deploy

This deploys the Cloud Functions, Firestore rules and indexes, Storage rules and Realtime Database rules defined in firebase.json. The first deploy can take several minutes.

or use one of the following commands to only deploy part(s) of the backend:

npx firebase deploy --only functions
npx firebase deploy --only firestore          # deploys both rules and indexes
npx firebase deploy --only firestore:indexes  # indexes only
npx firebase deploy --only firestore:rules    # rules only

See Firebase documentation for additional information.

Firestore indexes

Firestore indexes are defined in firestore/indexes.json and enable efficient queries on multiple fields. Indexes are deployed automatically with npx firebase deploy, or you can deploy only indexes with:

npx firebase deploy --only firestore:indexes

Important notes:

• Index creation happens asynchronously and can take several minutes for large collections
• You can monitor index build status in the Firebase console under Firestore > Indexes
• New queries that require indexes will fail until the index is fully built
• Indexes are automatically used by Firestore once available - no code changes needed

If you see an error like The query requires an index in your functions logs, check that the required index exists in firestore/indexes.json and has been deployed.

Frontend deployment

If you haven't already, register your web app and copy its config into frontend/firebase_config.ts. See Register the web app.

frontend/index.html isn't committed to the repo. If it doesn't exist yet, copy it from the example (./run_locally.sh also does this for you):

cp frontend/index.example.html frontend/index.html

If you'd like to include Google Analytics, replace the placeholder analytics ID in frontend/index.html (see the TODOs in the file) with your Google Analytics ID.

Tip: To locally run the frontend with the deployed Firebase backend, navigate to the frontend directory and run npm run start:prod.

Finally, build the frontend into the frontend/dist directory:

cd frontend
npm run build:prod

Then copy the contents of frontend/dist/ to the web server that hosts the platform, for example an Apache server's document root.

Cache busting

When you build for prod, you will get bundled assets with a hash included in their filenames. This ensures that old code isn't loaded from the browser cache when new code is available, guarantees that users always get the most current version, and moves deployments closer to atomicity (so users can't get files from different deployments). To make proper use of that, you need to configure the cache-control headers in your hosting environment as follows:

• A long long max-age for javascript files (31536000 is good)
• No caching for index.html. This ensures that users will always get the most current deployed version of the code.

Firebase hosting

If you're using Firebase Hosting, the following configuration works well (in firebase.json):

  "hosting": {
    "public": "frontend/dist",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
    "headers": [
      {
        "source": "**/*.@(js|css)",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public,max-age=31536000,immutable"
          }
        ]
      },
      {
        "source": "/index.html",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "no-cache"
          }
        ]
      }
    ]
  }

After your first deploy

Allow yourself to create experiments

Anyone with a Google account can log in, but only people on the allowlist can create and manage experiments.

1. In the Firebase console, open Firestore Database and start a collection called allowlist at the top level.
2. Add a document whose document ID is your email address (the one you log in with). It doesn't need any fields.

Repeat for each researcher who needs access.

Add LLM API keys

Agents need an API key for the model provider they use. These keys are not part of the Firebase setup: each experimenter adds them in the app.

1. Open your deployed frontend and log in.
2. Go to Settings and enter keys for the providers you'll use (Gemini, Claude, OpenAI-compatible or Ollama).

Troubleshooting

• npx firebase deploy fails for functions with a billing or API error: make sure the project is on the Blaze plan. On a new project, Firebase may also ask you to enable some Google Cloud APIs. Follow the link in the error and deploy again.
• "The query requires an index" in the function logs: Firestore indexes are still building, or weren't deployed. See Firestore indexes.
• You can log in but can't create experiments: check that your exact login email is a document ID in the allowlist collection.
• Sign-in fails on your domain: see Troubleshooting on the Firebase setup page.