Your Machine
├── NestJS → runs raw (npm run start:dev)
└── Docker Desktop
    └── meilisearch container → port 7700 exposed to host

MEILISEARCH_URL=http://localhost:7700

project-root/
├── .env                              ← secrets for this machine — never commit
├── .env.example                      ← committed template with placeholder values
├── docker-compose.yml                ← runs MeiliSearch (and optionally your app)
├── Dockerfile                        ← only needed if you run NestJS in Docker too
├── scripts/
│   └── create-meili-keys.sh          ← one-time key generation (run once per environment)
└── src/
    └── search/
        ├── index.ts                  ← barrel
        ├── search.module.ts          ← @Global module
        ├── search.service.ts         ← MeiliSearch client wrapper
        ├── search.config.ts          ← config via ConfigService
        └── indexes/
            ├── index.ts              ← barrel
            └── [feature].index.ts   ← one file per index (settings + type-safe queries)

// ❌ Old
import { MeiliSearch } from 'meilisearch';
const client = new MeiliSearch({ ... });

// ✅ Current
import { Meilisearch } from 'meilisearch';
const client = new Meilisearch({ ... });

# ─── MeiliSearch ─────────────────────────────────────────────────────────────
#
# Set MEILISEARCH_URL to match YOUR deployment topology:
#
#   NestJS in Docker + MeiliSearch in same Docker Compose:
#     MEILISEARCH_URL=http://meilisearch:7700
#
#   NestJS running raw on same machine as MeiliSearch Docker:
#     MEILISEARCH_URL=http://localhost:7700
#
#   NestJS on a separate server from MeiliSearch:
#     MEILISEARCH_URL=http://<MEILISEARCH_SERVER_IP>:7700
#
MEILISEARCH_URL=http://localhost:7700

MEILISEARCH_MASTER_KEY=your-master-key-minimum-16-chars-change-this
MEILISEARCH_BACKEND_KEY=fill-this-in-after-step-4
MEILISEARCH_SEARCH_KEY=fill-this-in-after-step-4

MEILISEARCH_URL=REPLACE_ME_see_comments_above
MEILISEARCH_MASTER_KEY=REPLACE_ME_min_16_chars
MEILISEARCH_BACKEND_KEY=REPLACE_ME_after_key_generation
MEILISEARCH_SEARCH_KEY=REPLACE_ME_after_key_generation

services:
  meilisearch:
    image: getmeili/meilisearch:v1.37.0   # ← pinned version, never :latest
    restart: unless-stopped               # auto-restarts on server reboot or crash
    ports:
      - "7700:7700"                       # exposes port to host
    environment:
      - MEILI_ENV=production              # enforces API key auth on ALL requests
      - MEILI_MASTER_KEY=${MEILISEARCH_MASTER_KEY}
      - MEILI_DB_PATH=/meili_data/data.ms
      - MEILI_DUMP_DIR=/meili_data/dumps
      - MEILI_SNAPSHOT_DIR=/meili_data/snapshots
      - MEILI_SNAPSHOT_INTERVAL_SEC=86400  # auto-snapshot every 24h
    volumes:
      - meilidata:/meili_data              # named volume — works on Windows, Mac, Linux
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7700/health"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

volumes:
  meilidata:

# ── Optional: add this service only if NestJS runs in Docker too ─────────────
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    env_file:
      - .env
    depends_on:
      meilisearch:
        condition: service_healthy     # waits for MeiliSearch to pass health check
    networks:
      - app-network
    restart: unless-stopped

# ── Add this network block only if you added the app service above ────────────
networks:
  app-network:
    driver: bridge

# ── Also add meilisearch to the same network if you added the app service ─────
# Under the meilisearch service, add:
#   networks:
#     - app-network
# And change MEILISEARCH_URL in .env to: http://meilisearch:7700

FROM node:20-alpine AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# ── Production image — no dev dependencies ───────────────────────────────────
FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=builder /app/dist ./dist

EXPOSE 3000
CMD ["node", "dist/main.js"]

docker compose up meilisearch -d

# Wait until healthy
docker compose ps
# meilisearch should show: healthy

curl http://localhost:7700/health
# → {"status":"available"}

#!/bin/bash
set -e

if [ -z "$MEILISEARCH_MASTER_KEY" ]; then
  echo "ERROR: MEILISEARCH_MASTER_KEY is not set."
  echo "Run: export MEILISEARCH_MASTER_KEY=your-key"
  exit 1
fi

MEILI_HOST="http://localhost:7700"

echo ""
echo "=== Creating backend key (full write access — NestJS server only) ==="
curl -s -X POST "${MEILI_HOST}/keys" \
  -H "Authorization: Bearer ${MEILISEARCH_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "backend-key",
    "description": "NestJS backend — write, index, search. Never expose to frontend.",
    "actions": [
      "documents.add",
      "documents.delete",
      "documents.get",
      "indexes.create",
      "indexes.get",
      "indexes.update",
      "indexes.delete",
      "settings.get",
      "settings.update",
      "tasks.get",
      "search"
    ],
    "indexes": ["*"],
    "expiresAt": null
  }'

echo ""
echo "=== Creating search-only key (safe to expose to frontend clients) ==="
curl -s -X POST "${MEILI_HOST}/keys" \
  -H "Authorization: Bearer ${MEILISEARCH_MASTER_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "search-key",
    "description": "Frontend search only — read only, no write access.",
    "actions": ["search"],
    "indexes": ["*"],
    "expiresAt": null
  }'

echo ""
echo "=== Done. Copy the 'key' field values above into your .env ==="
echo "  MEILISEARCH_BACKEND_KEY = key from backend-key response"
echo "  MEILISEARCH_SEARCH_KEY  = key from search-key response"

export MEILISEARCH_MASTER_KEY=your-master-key-here
bash scripts/create-meili-keys.sh

$masterKey = "your-master-key-here"

# Backend key
curl.exe -X POST "http://localhost:7700/keys" `
  -H "Authorization: Bearer $masterKey" `
  -H "Content-Type: application/json" `
  --data '{\"name\":\"backend-key\",\"actions\":[\"documents.add\",\"documents.delete\",\"documents.get\",\"indexes.create\",\"indexes.get\",\"indexes.update\",\"indexes.delete\",\"settings.get\",\"settings.update\",\"tasks.get\",\"search\"],\"indexes\":[\"*\"],\"expiresAt\":null}'

# Search key
curl.exe -X POST "http://localhost:7700/keys" `
  -H "Authorization: Bearer $masterKey" `
  -H "Content-Type: application/json" `
  --data '{\"name\":\"search-key\",\"actions\":[\"search\"],\"indexes\":[\"*\"],\"expiresAt\":null}'

MEILISEARCH_BACKEND_KEY=paste-backend-key-here
MEILISEARCH_SEARCH_KEY=paste-search-key-here

npm install meilisearch

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class SearchConfig {
  constructor(private readonly configService: ConfigService) {}

  // Reads MEILISEARCH_URL from .env
  // This is the only place the host is read — never hardcoded anywhere else
  get host(): string {
    const url = this.configService.get<string>('MEILISEARCH_URL');
    if (!url) throw new Error('MEILISEARCH_URL is not set in environment');
    return url;
  }

  // Backend key — used for all server-side operations (write + search)
  get backendApiKey(): string {
    const key = this.configService.get<string>('MEILISEARCH_BACKEND_KEY');
    if (!key) throw new Error('MEILISEARCH_BACKEND_KEY is not set in environment');
    return key;
  }

  // Search key — safe to return to frontend for direct client-side search
  get searchApiKey(): string {
    const key = this.configService.get<string>('MEILISEARCH_SEARCH_KEY');
    if (!key) throw new Error('MEILISEARCH_SEARCH_KEY is not set in environment');
    return key;
  }
}

import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { Meilisearch, Index, SearchParams, SearchResponse, Settings } from 'meilisearch';
import { SearchConfig } from './search.config';

@Injectable()
export class SearchService implements OnModuleInit {
  private readonly logger = new Logger(SearchService.name);
  private client: Meilisearch;

  constructor(private readonly config: SearchConfig) {}

  onModuleInit() {
    // host resolves from MEILISEARCH_URL in .env
    // works whether NestJS is in Docker, raw on Windows/Mac/Linux, or on a remote server
    this.client = new Meilisearch({
      host:   this.config.host,
      apiKey: this.config.backendApiKey,
    });

    this.logger.log(`MeiliSearch client initialized → ${this.config.host}`);
  }

  // ─── Health ───────────────────────────────────────────────────────────────

  async ping(): Promise<boolean> {
    try {
      await this.client.health();
      return true;
    } catch {
      return false;
    }
  }

  // ─── Index access ─────────────────────────────────────────────────────────

  getIndex<T>(indexName: string): Index<T> {
    return this.client.index<T>(indexName);
  }

  // ─── Documents ───────────────────────────────────────────────────────────

  async addDocuments<T extends Record<string, unknown>>(
    indexName: string,
    documents: T[],
    primaryKey = 'id',
  ) {
    const task = await this.client.index<T>(indexName).addDocuments(documents, { primaryKey });
    this.logger.log(`Enqueued addDocuments → ${indexName} (task ${task.taskUid})`);
    return task;
  }

  async updateDocuments<T extends Record<string, unknown>>(
    indexName: string,
    documents: T[],
    primaryKey = 'id',
  ) {
    const task = await this.client.index<T>(indexName).updateDocuments(documents, { primaryKey });
    this.logger.log(`Enqueued updateDocuments → ${indexName} (task ${task.taskUid})`);
    return task;
  }

  async deleteDocument(indexName: string, documentId: string | number) {
    const task = await this.client.index(indexName).deleteDocument(documentId);
    this.logger.log(`Enqueued deleteDocument → ${indexName}/${documentId} (task ${task.taskUid})`);
    return task;
  }

  async deleteDocuments(indexName: string, documentIds: Array<string | number>) {
    const task = await this.client.index(indexName).deleteDocuments(documentIds);
    this.logger.log(`Enqueued deleteDocuments → ${indexName} (${documentIds.length} docs, task ${task.taskUid})`);
    return task;
  }

  // ─── Search ───────────────────────────────────────────────────────────────

  async search<T>(
    indexName: string,
    query: string,
    params?: SearchParams,
  ): Promise<SearchResponse<T>> {
    return this.client.index<T>(indexName).search(query, params);
  }

  // ─── Settings ────────────────────────────────────────────────────────────

  async updateIndexSettings(indexName: string, settings: Settings) {
    const task = await this.client.index(indexName).updateSettings(settings);
    this.logger.log(`Enqueued updateSettings → ${indexName} (task ${task.taskUid})`);
    return task;
  }

  // ─── Tasks ───────────────────────────────────────────────────────────────

  async waitForTask(taskUid: number, timeoutMs = 30000) {
    return this.client.waitForTask(taskUid, { timeoutInMs: timeoutMs });
  }

  // ─── Backup ──────────────────────────────────────────────────────────────

  async createDump() {
    const task = await this.client.createDump();
    this.logger.log(`Dump creation enqueued (task ${task.taskUid})`);
    return task;
  }

  // ─── Raw client (escape hatch for SDK features not wrapped above) ─────────

  getClient(): Meilisearch {
    return this.client;
  }
}

import { Global, Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { SearchConfig } from './search.config';
import { SearchService } from './search.service';

@Global()   // any module can inject SearchService without re-importing SearchModule
@Module({
  imports:   [ConfigModule],
  providers: [SearchConfig, SearchService],
  exports:   [SearchConfig, SearchService],
})
export class SearchModule {}

export * from './search.module';
export * from './search.service';
export * from './search.config';
export * from './indexes';

import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { SearchService } from '../search.service';

export const PRODUCT_INDEX = 'products';

export interface ProductDocument {
  id:          string;
  name:        string;
  description: string;
  brand:       string;
  category:    string;
  price:       number;
  inStock:     boolean;
  createdAt:   string;
}

@Injectable()
export class ProductIndex implements OnModuleInit {
  private readonly logger = new Logger(ProductIndex.name);

  constructor(private readonly searchService: SearchService) {}

  async onModuleInit() {
    await this.applySettings();
  }

  private async applySettings() {
    try {
      const task = await this.searchService.updateIndexSettings(PRODUCT_INDEX, {
        // Only fields users will search — controls relevance and index size
        searchableAttributes: ['name', 'description', 'brand', 'category'],

        // Fields available for .filter() queries
        filterableAttributes: ['category', 'brand', 'price', 'inStock'],

        // Fields available for .sort() queries
        sortableAttributes: ['price', 'createdAt', 'name'],

        rankingRules: [
          'words',      // more query words matched = higher rank
          'typo',       // fewer typos = higher rank
          'proximity',  // query words closer together = higher rank
          'attribute',  // earlier searchableAttribute = higher rank
          'sort',       // user-specified sort order
          'exactness',  // exact match = higher rank
        ],

        typoTolerance: {
          enabled: true,
          minWordSizeForTypos: {
            oneTypo:  4,   // allow 1 typo for words >= 4 chars
            twoTypos: 8,   // allow 2 typos for words >= 8 chars
          },
        },

        pagination: {
          maxTotalHits: 1000,
        },
      });

      await this.searchService.waitForTask(task.taskUid);
      this.logger.log(`Settings applied → ${PRODUCT_INDEX}`);
    } catch (error) {
      // Log but do not throw — app still starts even if settings fail
      this.logger.error(`Failed to apply settings → ${PRODUCT_INDEX}`, (error as Error).stack);
    }
  }

  // ─── Type-safe query methods ──────────────────────────────────────────────

  async searchProducts(
    query: string,
    options?: {
      category?: string;
      brand?:    string;
      inStock?:  boolean;
      maxPrice?: number;
      page?:     number;
    },
  ) {
    const filters: string[] = [];
    if (options?.category)               filters.push(`category = "${options.category}"`);
    if (options?.brand)                  filters.push(`brand = "${options.brand}"`);
    if (options?.inStock !== undefined)  filters.push(`inStock = ${options.inStock}`);
    if (options?.maxPrice !== undefined) filters.push(`price <= ${options.maxPrice}`);

    return this.searchService.search<ProductDocument>(PRODUCT_INDEX, query, {
      filter:                filters.join(' AND '),
      hitsPerPage:           20,
      page:                  options?.page ?? 1,
      attributesToHighlight: ['name', 'description'],
    });
  }

  async indexProducts(products: ProductDocument[]) {
    return this.searchService.addDocuments(PRODUCT_INDEX, products, 'id');
  }

  async removeProduct(productId: string) {
    return this.searchService.deleteDocument(PRODUCT_INDEX, productId);
  }
}

export * from './product.index';
// export * from './[feature].index';  ← add each new index here

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { SearchModule } from './search';
import { ProductIndex } from './search/indexes';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    SearchModule,
    // ... rest of your modules
  ],
  providers: [
    ProductIndex,   // registers the OnModuleInit settings sync
  ],
})
export class AppModule {}

# 1. Start MeiliSearch (Docker Desktop must be running on Windows)
docker compose up meilisearch -d

# 2. Verify it's healthy
curl http://localhost:7700/health
# → {"status":"available"}

# 3. Start NestJS normally
npm run start:dev
# or
npm run start:prod

docker compose up --build -d
docker compose ps   # both services should show healthy/running

# On the MeiliSearch server:
docker compose up meilisearch -d

# On the NestJS server — .env has:
# MEILISEARCH_URL=http://<MEILISEARCH_SERVER_IP>:7700
npm run start:prod

import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
import { SearchService } from '../search.service';

export const MY_FEATURE_INDEX = 'my-feature';

export interface MyFeatureDocument {
  id:    string;
  title: string;
  body:  string;
  // only fields the search actually needs
}

@Injectable()
export class MyFeatureIndex implements OnModuleInit {
  private readonly logger = new Logger(MyFeatureIndex.name);

  constructor(private readonly searchService: SearchService) {}

  async onModuleInit() {
    try {
      const task = await this.searchService.updateIndexSettings(MY_FEATURE_INDEX, {
        searchableAttributes: ['title', 'body'],
        filterableAttributes: ['status', 'authorId'],
        sortableAttributes:   ['createdAt'],
      });
      await this.searchService.waitForTask(task.taskUid);
      this.logger.log(`Settings applied → ${MY_FEATURE_INDEX}`);
    } catch (error) {
      this.logger.error(`Settings failed → ${MY_FEATURE_INDEX}`, (error as Error).stack);
    }
  }

  async search(query: string) {
    return this.searchService.search<MyFeatureDocument>(MY_FEATURE_INDEX, query);
  }

  async index(documents: MyFeatureDocument[]) {
    return this.searchService.addDocuments(MY_FEATURE_INDEX, documents, 'id');
  }
}

export * from './my-feature.index';

providers: [MyFeatureIndex],

exports: [MyFeatureIndex],

import { writeSearchOutbox } from 'src/search/helpers/search-outbox.helper';

async createInvestment(data: any, userId: string) {
  return this.prisma.$transaction(async (tx) => {
    // 1. Create the entity
    const investment = await tx.investments.create({ data });

    // 2. Queue for Search Indexing (Atomic — same transaction)
    await writeSearchOutbox(tx, {
      entity_type: 'investments',
      entity_id: investment.id,
      action: 'UPSERT',
      user_id: userId,
      payload: { ...investment },
    });

    return investment;
  });
}

@Get()
@Throttle({ default: { limit: 120, ttl: 60000 } }) // Higher limit for fast debounced typing
async search(
  @GetAdmin('id') userId: string,
  @Query('q') query: string,
  @Query('service') service: string, // e.g. 'investments'
) {
  return this.searchService.search(service, query, { filter: `user_id = "${userId}"` });
}

const handleSearch = useDebouncedCallback(async (query: string) => {
  // Fire requests concurrently across multiple indices
  const [investments, accounts] = await Promise.all([
    axios.get(`/xam/search?q=${query}&service=investments`),
    axios.get(`/xam/search?q=${query}&service=accounts`)
  ]);
  setResults([...investments.data.hits, ...accounts.data.hits]);
}, 300); // 300ms debounce

# Create a dump
curl -X POST http://localhost:7700/dumps \
  -H "Authorization: Bearer ${MEILISEARCH_BACKEND_KEY}"
# → returns { "taskUid": 1 }

# Poll until status = "succeeded"
curl http://localhost:7700/tasks/1 \
  -H "Authorization: Bearer ${MEILISEARCH_BACKEND_KEY}"

# Dump file is at /meili_data/dumps/ inside the Docker volume

# Step 1: Create a dump from the running instance
curl -X POST http://localhost:7700/dumps \
  -H "Authorization: Bearer ${MEILISEARCH_BACKEND_KEY}"

# Step 2: Wait for task to succeed, note the dump filename

# Step 3: Update docker-compose.yml
#   getmeili/meilisearch:v1.37.0  →  getmeili/meilisearch:vX.Y.Z

# Step 4: Temporarily add import command to docker-compose.yml meilisearch service:
#   command: ["meilisearch", "--import-dump=/meili_data/dumps/YOUR_DUMP_FILE.dump"]

# Step 5: Start the new version
docker compose up meilisearch -d

# Step 6: Verify data is intact, then remove the --import-dump command line
# Step 7: Restart normally
docker compose up meilisearch -d --force-recreate

# Health check (from host machine — always localhost:7700)
curl http://localhost:7700/health
# → {"status":"available"}

# List API keys (uses master key)
curl http://localhost:7700/keys \
  -H "Authorization: Bearer ${MEILISEARCH_MASTER_KEY}"

# Verify backend key works
curl http://localhost:7700/indexes \
  -H "Authorization: Bearer ${MEILISEARCH_BACKEND_KEY}"

# Check logs
docker compose logs meilisearch
docker compose logs app   # only if NestJS is in Docker

import { Meilisearch } from 'meilisearch';

const client = new Meilisearch({
  host:   process.env.MEILISEARCH_URL,        // from .env — never hardcoded
  apiKey: process.env.MEILISEARCH_BACKEND_KEY,
});

const index = client.index('products');

// Add / update documents
await index.addDocuments(docs, { primaryKey: 'id' });
await index.updateDocuments(docs, { primaryKey: 'id' });

// Delete
await index.deleteDocument('doc-id-123');
await index.deleteDocuments(['id1', 'id2', 'id3']);
await index.deleteAllDocuments();

// Search
const results = await index.search('wireless headphones', {
  filter:                'category = "Electronics" AND price < 200',
  sort:                  ['price:asc'],
  hitsPerPage:           20,
  page:                  1,
  attributesToHighlight: ['name', 'description'],
});
// results.hits            — matched documents
// results.totalHits       — total count
// results.processingTimeMs — query latency in ms

// Settings (idempotent — safe to call on every startup)
await index.updateSettings({
  searchableAttributes: ['name', 'description'],
  filterableAttributes: ['category', 'price'],
  sortableAttributes:   ['price', 'createdAt'],
});

// All write operations are async — poll the task to confirm
const task   = await index.addDocuments(docs);
const result = await client.tasks.waitForTask(task.taskUid); // v0.40+ syntax
// result.status: 'succeeded' | 'failed' | 'enqueued' | 'processing'

// Health
const health = await client.health();
// health.status: 'available'

// ❌ Hardcoding the host in application code
const client = new Meilisearch({ host: 'http://localhost:7700' });
// ✅ Always read from environment
const client = new Meilisearch({ host: process.env.MEILISEARCH_URL });

// ❌ Using master key in application code
const client = new Meilisearch({ apiKey: process.env.MEILISEARCH_MASTER_KEY });
// ✅ Use the scoped backend key
const client = new Meilisearch({ apiKey: process.env.MEILISEARCH_BACKEND_KEY });

// ❌ Using :latest Docker image tag
image: getmeili/meilisearch:latest
// ✅ Always pin to a specific version
image: getmeili/meilisearch:v1.37.0

// ❌ MEILI_ENV not set — anyone can hit the API without a key
// ✅ Always set
- MEILI_ENV=production

// ❌ Using MEILISEARCH_URL=http://meilisearch:7700 when NestJS runs outside Docker
//    Docker service names only resolve inside Docker networks
// ✅ Use localhost:7700 when NestJS runs raw on the same machine as Docker

// ❌ Using MEILISEARCH_URL=http://localhost:7700 when NestJS runs inside Docker
//    localhost inside a container = the container itself, not the host
// ✅ Use http://meilisearch:7700 (service name) when both are in same Docker Compose

// ❌ Opening port 7700 to the public internet when MeiliSearch is on a separate server
// ✅ Restrict firewall to allow 7700 only from the NestJS server's IP

// ❌ Host-path volume mounts — permission/performance issues on Windows and Mac
volumes:
  - ./meili_data:/meili_data
// ✅ Named Docker volumes — works everywhere
volumes:
  - meilidata:/meili_data

// ❌ Not setting searchableAttributes — MeiliSearch indexes all fields by default
//    Causes large index sizes and slower search on documents with many fields
// ✅ Always set searchableAttributes explicitly in per-index OnModuleInit

// ❌ Upgrading Docker image version without creating a dump first
// ✅ Always dump → upgrade → import