Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/algolia-pack/skills/algolia-prod-checklist/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill algolia-prod-checklist. Copyright stays with the author (MIT).

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 ""
echo "All checks passed. Ready to deploy."

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

Resources

• Algolia Dashboard
• Algolia Status
• Index Settings Reference

Next Steps

For version upgrades, see algolia-upgrade-migration.