Skip to content

fix: docs: backend setup - API Key index#3653

Merged
smian1 merged 1 commit into
BasedHardware:mainfrom
neooriginal:fix-backend-setup-docs
Dec 9, 2025
Merged

fix: docs: backend setup - API Key index#3653
smian1 merged 1 commit into
BasedHardware:mainfrom
neooriginal:fix-backend-setup-docs

Conversation

@neooriginal
Copy link
Copy Markdown
Collaborator

This pull request adds an important setup step to the backend documentation, clarifying requirements for Firestore composite indexes. This will help prevent API key query failures and improve onboarding for new developers.

Documentation update:

  • Added instructions to create composite indexes for dev_api_keys and mcp_api_keys collections in Firestore, specifying the required fields and their sort order. This is necessary to avoid internal server errors when loading API keys in the Developer Settings page.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds an important documentation step for setting up the backend, specifically regarding the creation of Firestore composite indexes for API key queries. The change is clear and correctly identifies a necessary step to prevent errors. My review includes a suggestion to automate this setup process to make it more robust and less error-prone for developers, which I've classified as a high-severity improvement for project maintainability.

Comment thread backend/README.md
Comment on lines +14 to +20
- **Firestore Composite Indexes:** You must create composite indexes for API key queries. Go to [Firebase Console](https://console.firebase.google.com/) → Firestore Database → Indexes, and create the following composite indexes:
| Collection | Fields |
|------------|--------|
| `dev_api_keys` | `user_id` (Ascending) + `created_at` (Descending) |
| `mcp_api_keys` | `user_id` (Ascending) + `created_at` (Descending) |

Without these indexes, the Developer Settings page will show "Failed to load API keys: Internal Server Error".
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

Thank you for documenting this crucial setup step. To make the process more robust and less error-prone for new developers, I recommend automating the creation of these Firestore indexes. Instead of manual steps, you can define the indexes in a firestore.indexes.json file and have developers deploy them with a single command.

This involves:

  1. Creating a firestore.indexes.json file in the backend/ directory.
  2. Updating firebase.json to point to this file.
  3. Replacing the manual instructions in the README with a command to deploy the indexes.

Here is the content for firestore.indexes.json:

{
  "indexes": [
    {
      "collectionGroup": "dev_api_keys",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "user_id", "order": "ASCENDING" },
        { "fieldPath": "created_at", "order": "DESCENDING" }
      ]
    },
    {
      "collectionGroup": "mcp_api_keys",
      "queryScope": "COLLECTION",
      "fields": [
        { "fieldPath": "user_id", "order": "ASCENDING" },
        { "fieldPath": "created_at", "order": "DESCENDING" }
      ]
    }
  ]
}

And in firebase.json:

{
  "firestore": {
    "indexes": "firestore.indexes.json"
  }
}

The suggested change below updates the README accordingly.

Suggested change
- **Firestore Composite Indexes:** You must create composite indexes for API key queries. Go to [Firebase Console](https://console.firebase.google.com/) → Firestore Database → Indexes, and create the following composite indexes:
| Collection | Fields |
|------------|--------|
| `dev_api_keys` | `user_id` (Ascending) + `created_at` (Descending) |
| `mcp_api_keys` | `user_id` (Ascending) + `created_at` (Descending) |
Without these indexes, the Developer Settings page will show "Failed to load API keys: Internal Server Error".
- **Firestore Composite Indexes:** This project uses Firestore composite indexes for querying API keys. To deploy them, run the following command from the `backend` directory:
```bash
firebase deploy --only firestore:indexes
```
This command uses the definitions in `firestore.indexes.json`. Without these indexes, the Developer Settings page will show "Failed to load API keys: Internal Server Error".

@neooriginal neooriginal changed the title fix docs: backend setup fix: docs: backend setup Dec 8, 2025
@neooriginal neooriginal changed the title fix: docs: backend setup fix: docs: backend setup - API Key index Dec 8, 2025
@smian1 smian1 self-assigned this Dec 9, 2025
@smian1 smian1 self-requested a review December 9, 2025 10:43
@smian1 smian1 merged commit 4e8cb4a into BasedHardware:main Dec 9, 2025
@neooriginal neooriginal deleted the fix-backend-setup-docs branch December 9, 2025 10:48
Glucksberg pushed a commit to Glucksberg/omi-local that referenced this pull request Apr 28, 2026
This pull request adds an important setup step to the backend
documentation, clarifying requirements for Firestore composite indexes.
This will help prevent API key query failures and improve onboarding for
new developers.

Documentation update:

* Added instructions to create composite indexes for `dev_api_keys` and
`mcp_api_keys` collections in Firestore, specifying the required fields
and their sort order. This is necessary to avoid internal server errors
when loading API keys in the Developer Settings page.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants