fix: docs: backend setup - API Key index#3653
Conversation
There was a problem hiding this comment.
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.
| - **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". |
There was a problem hiding this comment.
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:
- Creating a
firestore.indexes.jsonfile in thebackend/directory. - Updating
firebase.jsonto point to this file. - 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.
| - **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". |
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.
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:
dev_api_keysandmcp_api_keyscollections 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.