typo3-solr

name	typo3-solr
description	Runs and debugs the site's own search with Apache Solr in TYPO3 (EXT:solr): what gets indexed and why results come back empty after adding a new page type, facets for category or year on the results page, autocomplete and suggest, PDF and file indexing through Tika, and an indexing queue that is stuck. Use when searching the site returns nothing or the wrong things, or when configuring configsets, custom indexers, routing, solrfal or vector search. Visibility in external search engines is typo3-seo.
compatibility	TYPO3 14.x
metadata	{"version":"1.0.0","related_skills":"typo3-content-blocks, typo3-datahandler, typo3-seo, ai-search-optimization","origin":"webconsulting"}
license	MIT / CC-BY-SA-4.0

Apache Solr for TYPO3

Source: https://github.com/dirnbauer/webconsulting-skills

Compatibility: This skill targets TYPO3 v14.x. Match EXT:solr (and Solr server version) using the official Version Matrix and Packagist — 14.0.x availability may lag docs; use the branch/matrix the project documents until a stable tag ships. All custom PHP examples use TYPO3 v14 conventions (PHP 8.2+, constructor promotion, #[AsEventListener] where shown).

TYPO3 API First: Always use TYPO3's built-in APIs and EXT:solr's TypoScript/PSR-14 events before creating custom implementations. Do not reinvent what EXT:solr already provides.

Sources

This skill is based on the following authoritative sources:

1. EXT:solr Documentation
2. EXT:tika Documentation
3. Version Matrix
4. GitHub: TYPO3-Solr/ext-solr
5. GitHub: main branch (14.0.x-dev)
6. Apache Solr Reference Guide
7. Solr Dense Vector Search
8. Solr Text to Vector (LLM)
9. typo3-solr.com
10. hosted-solr.com
11. ddev-typo3-solr
12. Mittwald Solr Docs
13. helhum/dotenv-connector

1. Architecture Overview

EXT:solr connects TYPO3 CMS to an Apache Solr search server, providing full-text search, faceted navigation, autocomplete, and (on supported Solr 9.x builds) dense-vector / semantic features where enabled.

graph LR
    subgraph typo3 [TYPO3 CMS]
        Editor[Editor creates/edits content]
        Monitor[Monitoring detects changes]
        Queue[Index Queue]
        Scheduler[Scheduler Worker]
        Plugin[Search Plugin]
    end
    subgraph solr [Apache Solr Server]
        Core[Solr Core]
        Schema[Schema / Configset]
    end
    Editor --> Monitor
    Monitor --> Queue
    Queue --> Scheduler
    Scheduler -->|HTTP POST documents| Core
    Plugin -->|HTTP GET query| Core
    Core --> Plugin

Document Lifecycle

sequenceDiagram
    participant E as Editor
    participant T as TYPO3
    participant M as Monitor
    participant Q as Index Queue
    participant S as Scheduler
    participant Solr as Solr Server

    E->>T: Create/edit record
    T->>M: DataHandler triggers PSR-14 event
    M->>Q: Add/update queue item
    Note over Q: tx_solr_indexqueue_item
    S->>Q: Poll for pending items
    Q->>S: Return items to index
    S->>Solr: POST document (JSON)
    Solr-->>S: 200 OK
    S->>Q: Mark item as indexed

Component Overview

Component	Package	Purpose	Required?
EXT:solr	apache-solr-for-typo3/solr	Core search integration	Yes
EXT:tika	apache-solr-for-typo3/tika	Text/metadata extraction from files	Only for file indexing
EXT:solrfal	Funding extension	FAL file indexing into Solr	Only for file indexing
EXT:solrconsole	Funding extension	Backend management console	Optional
EXT:solrdebugtools	Funding extension	Query debugging, score analysis	Optional (recommended for dev)

2. Version compatibility matrix (upstream)

Target for this skill: TYPO3 v14.x with the EXT:solr release row that matches your Core on the official Version Matrix. Older rows are reference only for legacy sites.

EXT:solr	TYPO3	Apache Solr	Configset	PHP	EXT:tika	EXT:solrfal
14.0.x (see matrix / Packagist)	14.x	per matrix	ext_solr_14_0_0 (when used)	^8.2	per matrix	per matrix
13.1.x	(not a target for this collection)	9.10.1	ext_solr_13_1_0	^8.2	13.1	13.0

While 14.0.x has no stable tag on Packagist (betas are published), follow the TYPO3 v14 Readiness subsection below (^14.0@beta / docs workflow) until a stable tag ships.

TYPO3 v14 Readiness

The Version Matrix targets TYPO3 14.3 + EXT:solr 14.0 + Apache Solr 10.0.0 + ext_solr_14_0_0 (Solr 9.10.1 belongs to EXT:solr 13.1/12.1). Upstream development is on main:

• main requires typo3/cms-core: ^v14.3.0 (see composer.json on main)
• branch alias dev-main -> 14.0.x-dev
• Composer reality check: 14.0.0-beta1–beta3 are published on Packagist; no stable 14.0 tag exists yet, so install via the @beta stability flag (or fall back to dev-main for the bleeding edge).

Until a stable 14.0 is published on Packagist:

composer require apache-solr-for-typo3/solr:^14.0@beta

Warning: Re-check Packagist/GitHub when you upgrade — switch from ^14.0@beta to a plain ^14.0 constraint as soon as stable releases exist.

CVE-2025-24814 Migration

Apache Solr 9.8.0+ disables loading jar files via lib directive in configsets. CVE-2025-24814 is a remote-code-execution class issue: if an attacker can replace or supply a configset file that Solr treats as trusted, Solr may load attacker-controlled JARs from that configset (including via the lib directive), which can lead to arbitrary code execution. The stricter default blocks that classpath loading from configsets. The solr-typo3-plugin must be moved from /configsets/ext_solr_*/typo3lib/ to /typo3lib/ at the Solr server root. Docker users: use the EXT:solr container image 13.0.1+ (image tag, not TYPO3 Core) so this migration runs automatically.

3. Installation & Setup

Composer

composer require apache-solr-for-typo3/solr

DDEV Setup

The recommended local development setup uses the ddev-typo3-solr addon:

ddev add-on get ddev/ddev-typo3-solr
ddev restart

Solr image version: the DDEV Solr add-on defaults SOLR_BASE_IMAGE to solr:9.10, and the generated compose file is .ddev/docker-compose.typo3-solr.yaml. For explicit control, override via .ddev/.env.typo3-solr (for example: ddev dotenv set .ddev/.env.typo3-solr --solr-base-image="solr:9.10.1") and rebuild the Solr service.

Configure .ddev/typo3-solr/config.yaml:

config: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/solr.xml'
typo3lib: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/typo3lib'
configsets:
  - name: 'ext_solr_14_0_0'
    path: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/configsets/ext_solr_14_0_0'
    cores:
      - name: 'core_en'
        schema: 'english/schema.xml'
      - name: 'core_de'
        schema: 'german/schema.xml'

Auto-initialize cores on boot in .ddev/config.yaml:

hooks:
  post-start:
    - exec-host: ddev solrctl apply

Useful DDEV commands:

Command	Description
ddev solrctl apply	Create cores from config
ddev solrctl wipe	Delete all cores
ddev exec -s typo3-solr solr --version	Check Solr version inside the Solr service
ddev launch :8984	Open Solr Admin UI
ddev logs -s typo3-solr	View Solr logs

Docker (Production)

services:
  solr:
    # Note: as of March 2026, no stable 14.0 tag exists on Docker Hub.
    # Use 14.0.x-dev for testing, or 13.1 for production until 14.0 ships.
    image: typo3solr/ext-solr:14.0.x-dev
    ports:
      - "8983:8983"
    volumes:
      - solr-data:/var/solr
    restart: unless-stopped

volumes:
  solr-data:
    driver: local

The image ships default cores for all languages. Persistent data is stored at /var/solr (owned by UID 8983).

Standalone Solr

Deploy the configset from EXT:solr into your Solr installation:

cp -r vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/* $SOLR_INSTALL_DIR/server/solr/

Create cores via core.properties files, solrctl, or the Solr Admin API. Payload shape differs by Solr major (v8 vs v9 “v2” APIs) — treat any one-liner curl as illustrative and follow the Solr version you run.

# Illustrative only — confirm against your Solr admin API docs / use bin/solr or ddev solrctl for local setups
curl -sS -X POST "http://localhost:8983/solr/admin/cores?action=CREATE&name=core_en&configSet=ext_solr_14_0_0"

Managed Hosting: Mittwald

Mittwald provides a managed Solr service via their container platform. Use the Terraform module:

module "solr" {
  source         = "mittwald/solr/mittwald"
  solr_version   = "9"
  solr_core_name = "typo3"
  solr_heap      = "2g"
}

Access Solr at http://typo3-solr:8983 inside the container. For local debugging:

mw container port-forward --port 8983

Managed Hosting: hosted-solr.com

hosted-solr.com by dkd provides pre-configured Solr cores optimized for EXT:solr. As of the live pricing page, the Small plan is 10,00 EUR/month (2 Solr indexes, 4.000 documents; VAT note on site). After creating a core, configure it in your TYPO3 site config using the provided host, port, and path.

TYPO3 Site Configuration

In config/sites/<identifier>/config.yaml:

solr_enabled_read: true
solr_host_read: solr
solr_port_read: '8983'
solr_scheme_read: http
solr_path_read: /
solr_core_read: core_en

For DDEV, use the DDEV hostname and HTTPS port:

solr_host_read: <project>.ddev.site
solr_port_read: '8984'
solr_scheme_read: https

Environment Configuration (helhum/dotenv-connector)

Never hardcode Solr connection details. Use helhum/dotenv-connector for per-environment configuration:

composer require helhum/dotenv-connector

.env (gitignored):

SOLR_HOST=solr
SOLR_PORT=8983
SOLR_SCHEME=http
SOLR_PATH=/
SOLR_CORE_EN=core_en
SOLR_CORE_DE=core_de

.env.example (committed to VCS):

SOLR_HOST=solr
SOLR_PORT=8983
SOLR_SCHEME=http
SOLR_PATH=/
SOLR_CORE_EN=core_en
SOLR_CORE_DE=core_de

In config/system/additional.php, override site config values programmatically or use a post-processing approach. For simple setups, keep .env values and reference them in deployment scripts that generate site config YAML per environment.

4. EXT:tika -- When You Need It (and When Not)

EXT:tika integrates Apache Tika for metadata extraction, language detection, and text extraction from over 1,000 file formats.

graph TD
    Question{"Do you index files?<br/>(PDF, DOCX, XLSX)"}
    Question -->|Yes| NeedTika[Install EXT:tika + EXT:solrfal]
    Question -->|No| SkipTika[Skip -- EXT:solr handles<br/>pages and records natively]
    NeedTika --> TikaServer["Run Tika Server 3.2.3+<br/>(Docker recommended)"]

Three backends (choose one):

Backend	Recommended?	Setup
Tika Server	Yes	Standalone Docker container, newest Tika version
Solr Cell	Acceptable	Uses Tika built into Solr, no extra service needed
Tika App	Deprecated	Requires Java on webserver, do not use

When you NEED EXT:tika:

• File indexing via EXT:solrfal (search inside PDFs, Word documents, etc.)
• Automatic FAL metadata enrichment (EXIF, XMP, document properties)
• Language detection on uploaded files

When you DON'T need it:

• Only indexing pages and structured records (news, events, products) via Index Queue
• EXT:solr handles page content and record fields natively without Tika

Version: EXT:tika 13.1 (the current v13 release) requires Apache Tika Server/App 3.2.3+. A v14-compatible EXT:tika release is not yet available on the official Version Matrix — track Packagist and GitHub for updates. For Apache Tika and Solr security advisories, verify on Apache Solr security / vendor advisories.

See SKILL-SOLRFAL.md for complete file indexing setup.

Detailed Reference

Read the full guide when the task needs detailed examples, long templates, troubleshooting matrices, appendices, or sections not included above. Keep this file unloaded for narrow tasks so the skill follows progressive disclosure.