algolia-prod-checklist

name	algolia-prod-checklist
description	Execute Algolia production readiness checklist: index settings, key security, replica configuration, monitoring, and rollback procedures. Trigger: "algolia production", "deploy algolia", "algolia go-live", "algolia launch checklist", "algolia production ready".
allowed-tools	Read, Bash(curl:*), Bash(npm:*), Grep
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","search","algolia"]
compatibility	Designed for Claude Code

Algolia Production Checklist

Overview

Complete checklist for deploying Algolia search to production. Covers index configuration, API key security, replica setup, monitoring, and rollback procedures.

Prerequisites

• A named production index, deployment owner, rollback decision maker, and change window.
• Read-only verification credentials plus separate, least-privileged deployment credentials.
• Current monitoring and alert destinations tested before the release begins.

Instructions

Run the checklist in order, record each result, and stop the deployment on any failed security, relevance, or availability requirement. Use the verification script only after every prerequisite configuration item is confirmed.

Examples

The checklist and pre-deploy script are the release example: run them against the intended production index and attach the results to the deployment record before enabling the new search experience.

Pre-Production Checklist

Index Configuration

• searchableAttributes ordered by priority (first = highest)
• attributesForFaceting set for all filterable attributes
• customRanking configured (business metrics as tie-breakers)
• unretrievableAttributes set for fields that should be searchable but not returned
• attributesToRetrieve limited to fields needed by the UI
• typoTolerance tested (default: enabled, min 4 chars for 1 typo, min 8 for 2)
• removeStopWords configured for your language(s)
• distinct set if deduplication needed (e.g., one result per product group)

// Verify production settings
const settings = await client.getSettings({ indexName: 'products' });
console.log(JSON.stringify(settings, null, 2));

API Key Security

• Admin key in backend env vars only (never frontend)
• Search-Only key used in frontend with referers restriction
• maxQueriesPerIPPerHour set on all public keys
• maxHitsPerQuery limited on search keys
• Secured API keys used for multi-tenant data isolation
• Keys restricted to specific indexes where possible

Replicas (Alternate Sorting)

// Replicas give users alternate sort orders
await client.setSettings({
  indexName: 'products',
  indexSettings: {
    // Standard replicas: share parent's data, use their own relevance settings
    replicas: [
      'products_price_asc',    // Sort by price ascending
      'products_price_desc',   // Sort by price descending
      'products_newest',       // Sort by newest first
    ],
  },
});

// Configure each replica's ranking
await client.setSettings({
  indexName: 'products_price_asc',
  indexSettings: {
    ranking: [
      'asc(price)',    // Primary: price ascending
      'typo', 'geo', 'words', 'filters', 'proximity', 'attribute', 'exact', 'custom',
    ],
  },
});

Monitoring

• Health check endpoint tests Algolia connectivity
• Alert on error rate > 1% over 5 minutes
• Alert on P95 latency > 200ms (Algolia is typically < 50ms)
• Dashboard shows queries/sec, latency, error rate
• status.algolia.com RSS/webhook configured

// Health check endpoint
async function algoliaHealthCheck() {
  const start = Date.now();
  try {
    const { items } = await client.listIndices();
    const latencyMs = Date.now() - start;
    return {
      status: 'healthy',
      latencyMs,
      indexCount: items.length,
      totalRecords: items.reduce((sum, i) => sum + (i.entries || 0), 0),
    };
  } catch (error) {
    return { status: 'unhealthy', error: String(error), latencyMs: Date.now() - start };
  }
}

Graceful Degradation

// If Algolia is down, fall back to database search
async function searchWithFallback(query: string) {
  try {
    const { hits } = await client.searchSingleIndex({
      indexName: 'products',
      searchParams: { query, hitsPerPage: 20 },
    });
    return { source: 'algolia', results: hits };
  } catch (error) {
    console.error('Algolia unavailable, falling back to DB', error);
    const dbResults = await db.products.find({
      name: { $regex: query, $options: 'i' },
    }).limit(20);
    return { source: 'database', results: dbResults };
  }
}

Pre-Deploy Verification Script

#!/bin/bash
echo "=== Algolia Production Pre-Flight ==="

# 1. Verify connectivity
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}")
echo "API connectivity: HTTP $HTTP_CODE"
[ "$HTTP_CODE" != "200" ] && echo "FAIL: Cannot reach Algolia" && exit 1

# 2. Check Algolia service status
STATUS=$(curl -s https://status.algolia.com/api/v2/status.json | jq -r '.status.indicator')
echo "Algolia status: $STATUS"
[ "$STATUS" != "none" ] && echo "WARNING: Algolia reporting issues"

# 3. Verify index has data
RECORDS=$(curl -s "https://${ALGOLIA_APP_ID}-dsn.algolia.net/1/indexes/products" \
  -H "X-Algolia-Application-Id: ${ALGOLIA_APP_ID}" \
  -H "X-Algolia-API-Key: ${ALGOLIA_ADMIN_KEY}" | jq '.entries')
echo "Products index: $RECORDS records"
[ "$RECORDS" -lt 1 ] && echo "FAIL: Index is empty" && exit 1

echo 
 

Output

The release record contains completed configuration, security, monitoring, degradation, and verification checks, with failed items converted into explicit blockers or rollback actions. It does not authorize deployment when a required check is unknown.

Error Handling

Alert	Condition	Severity	Action
Search errors	5xx or 403 errors > 5/min	P1	Check API keys, Algolia status
High latency	P95 > 200ms for 5+ min	P2	Check index size, network
Rate limited	429 errors > 10/min	P2	Reduce request rate, check key limits
Index stale	Last updated > 1 hour ago	P3	Check sync pipeline

Resources

• Algolia Dashboard
• Algolia Status
• Index Settings Reference

Next Steps

For version upgrades, see algolia-upgrade-migration.