..  include:: /Includes.rst.txt

..  _feature-site-configuration-seeding:

====================================
Feature: Seeding site configurations
====================================

Description
===========

A seed set writes the site configurations its page tree needs, from a template
shipped next to the set:

..  code-block:: yaml
    :caption: packages/my_extension/Configuration/DataFactory/demo/config.yml

    sites:
      - identifier: main
        rootPage: 1000
        template: 'Sites/main'
        base: 'https://example.com/'

A template is a directory holding a :file:`config.yaml` and optionally a
:file:`settings.yaml` - the shape of a site below :file:`config/sites/`, so a
template is produced by copying a working site out of an installation. Its
default location is :file:`Sites/<identifier>/` next to the entry file of the
set.

:yaml:`rootPage` is the **uid** of the page that becomes the site root: the
:yaml:`id` an entity of the :sql:`pages` table declares in one of the scenario
files of the set. A scenario record carries no symbolic name, so the uid it
declares is its stable handle. A site whose :yaml:`rootPage` no :sql:`pages`
entity declares is refused before anything is written, rather than after the
whole page tree exists.

The site itself is written after the records, and the uid the page was actually
written with always wins over whatever the template declares.

Two refusals and one report belong to this:

*   **An existing site identifier is refused.** TYPO3 merges an incoming site
    configuration into an existing one, so seeding over it would produce neither
    the template nor the previous configuration. Remove the site first if the
    seed is meant to replace it.
*   **The automatic site configuration is suppressed.** TYPO3 writes an
    ``autogenerated-<uid>`` configuration for every new site root; an import
    switches that off for the whole run, whether the set declares
    :yaml:`sites` or not.
*   **A seeded site root covered by no site configuration is reported**, by
    uid. That is a page tree no frontend can render, and the suppression above
    is what would otherwise make it silent.

:bash:`--base` replaces the ``base`` of every site the run writes, which is what
lets one set be imported into several installations.
:bash:`--no-site-config` skips the declared site configurations while keeping
the report.

..  note::

    :bash:`--force` is refused for a set that declares :yaml:`sites` and
    suggests page uids the installation already uses. Forcing gives up the
    suggested uids of the whole colliding table, so the root page would be
    written under a different uid than the site names.

Impact
======

A seeded installation is reachable in the frontend without a manual step in the
backend, and an installation whose sites are maintained elsewhere is told which
of its new page trees are still uncovered.