services:
  searxng:
    # ⚠ `:latest` means "latest AT PULL TIME", and nothing re-pulls on its own.
    # On 2026-09-03 this instance was found running 2026.4.17 — 4.5 months old —
    # while reporting `healthy` and returning ZERO results for every query,
    # because SearXNG engine scrapers rot as upstream sites change their markup
    # and the project ships near-daily releases to keep up. `docker compose pull
    # && up -d` is the update; scripts/searxng-health.sh is what tells you it is
    # needed, because /healthz cannot.
    image: searxng/searxng:latest
    container_name: searxng
    restart: unless-stopped
    ports:
      - 9996:8080
    volumes:
      - /opt/docker/conf/searxng/searxng-settings.yml:/etc/searxng/settings.yml:ro
    environment:
      - SEARXNG_SECRET=${SEARXNG_SECRET}
      # Brave Search API key (vault: nh3-docker/searxng-brave-api-key).
      # ⚠ NOTHING READS THIS. It was added on the belief that settings.yml could
      # pull it via `!ENV SEARXNG_BRAVE_API_KEY`; this build has no !ENV YAML
      # constructor, so that attempt crash-looped the container ten times with
      # search down fleet-wide. The loader reads only SEARXNG_SETTINGS_PATH and
      # the entrypoint substitutes only `ultrasecretkey`. The key is therefore
      # inline in searxng-settings.yml by operator decision. Kept here, unused,
      # so it is ready if upstream ever gains env interpolation — remove it
      # rather than believing the comment it replaced.
      - SEARXNG_BRAVE_API_KEY=${SEARXNG_BRAVE_API_KEY}
      - BASE_URL=http://10.100.50.40:9996/
      - INSTANCE_NAME=SearXNG
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
        reservations:
          memory: 128M
    # ⚠ `--tries=1` MUST keep its `=1`. Written as two argv entries
    # (`- --tries` / `- --spider`) wget consumes `--spider` as the VALUE of
    # `--tries`, spider mode never engages, and every probe DOWNLOADS the
    # response to a file. On the ana-docker instance that left 295,287
    # `healthz.N` files in the container's writable layer, one per probe since
    # April; wget scanning them to pick the next free name is what blew the 10s
    # timeout and made the dashboard card flap. Self-worsening — each probe made
    # the next slower. Watch for `docker exec searxng ls | wc -l` climbing.
    #
    # ⚠ AND KNOW WHAT THIS PROBE DOES NOT TELL YOU: /healthz proves the web app
    # answers. It says nothing about whether any engine returns a result. Seven
    # days of `healthy` sat on top of a search box that found nothing.
    healthcheck:
      test:
        - CMD
        - wget
        - --no-verbose
        - --tries=1
        - --spider
        - http://localhost:8080/healthz
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s
    networks:
      - tnet
    labels:
      - homepage.group=Daily
      - homepage.name=SearXNG
      - homepage.icon=si-searxng
      - homepage.description=Privacy-respecting meta-search
      - homepage.href=http://10.100.50.40:9996

networks:
  tnet:
    name: traefik-net
    external: true