.. include:: ../Includes.txt


.. _installation:

============
Installation
============


.. _quickstart:

Quick start
===========

The recommended way to install this extension is via Composer:

..  code-block:: bash
    :caption: Install via Composer

    composer require nitsan/ns-t3af
    ./vendor/bin/typo3 extension:setup
    ./vendor/bin/typo3 cache:flush

Classic TYPO3 sites can also install from the
`TYPO3 Extension Repository (TER) <https://extensions.typo3.org/extension/ns_t3af>`__.

After installation:

1. Activate the extension in :guilabel:`Admin Tools > Extensions`.
2. Open :guilabel:`AI Foundation > Dashboard` and confirm the module group is
   available.
3. Connect providers and API keys in :guilabel:`AI Foundation > AI Providers`.
4. Complete guided options with :guilabel:`Quick Setup` in the AI Foundation
   module header.
5. Clear caches in :guilabel:`Admin Tools > Maintenance`.

.. figure:: ../Images/quick-setups.png
   :alt: AI Foundation Quick Setup wizard welcome step
   :class: with-border with-shadow

   Quick Setup wizard — guided first-time configuration in the AI Foundation module.

Continue with :ref:`Configuration <configuration>` for providers, MCP, and
day-to-day module setup.

Composer installation
=====================

.. _system-requirements:

Requirements
------------

Ensure your system meets these requirements:

* **TYPO3** — 12.4 LTS, 13.4 LTS, or 14.x
* **PHP** — 8.2 or higher (8.3 recommended), including ``ext-sodium``
* **Composer** — 2.x
* **Database** — MySQL 8.0+ or MariaDB 10.3+
* **Network** — Outbound HTTPS for AI provider API calls (not required for
  local-only Ollama setups)

Required Extensions
-------------------

Install and activate these extensions before AI Foundation:

* **scheduler** — Background AI jobs and scheduled tasks
* **workspaces** — Draft workspaces, MCP workflows, and safe content editing

``scheduler`` and ``workspaces`` ship with TYPO3. Activate them if they are
not already enabled.

No licence key is required for AI Foundation.

Install AI Foundation
---------------------

Find AI Foundation on the
`TYPO3 Extension Repository <https://extensions.typo3.org/extension/ns_t3af>`__.

..  code-block:: bash
    :caption: Install AI Foundation via Composer

    composer require nitsan/ns-t3af

Or use :guilabel:`Admin Tools > Extensions > Get Extensions`, search for
``ns_t3af`` (or **T3AF**), install and activate it, then flush caches.

Activate the extension
~~~~~~~~~~~~~~~~~~~~~~

Confirm ``ns_t3af`` is active in :guilabel:`Admin Tools > Extensions`.

Set up the database and clear caches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

..  code-block:: bash
    :caption: Extension setup and cache flush

    ./vendor/bin/typo3 extension:setup
    ./vendor/bin/typo3 cache:flush

Manual installation
===================

If you cannot use Composer, install from the TER:

1. Open :guilabel:`Admin Tools > Extensions > Get Extensions`.
2. Search for ``ns_t3af`` (or **T3AF**), install and activate it.
3. Run **Analyze Database Structure**.
4. Flush caches again.

.. warning::

   Manual installation requires manual dependency management. Composer
   installation is strongly recommended.

Verify the installation
=======================

Confirm that:

* ``ns_t3af`` is listed as active in :guilabel:`Admin Tools > Extensions`
* The **AI Foundation** module group appears in the backend sidebar
* **Analyze Database Structure** reports no pending changes for ``ns_t3af``

If the module is missing, flush caches and run
``./vendor/bin/typo3 extension:setup`` again.

Composer troubleshooting
==========================

Production installs must resolve a **stable Packagist tag** for ``nitsan/ns-t3af``.
Do not ship a ``composer.lock`` that pins a disposable ``dev-dep/*`` branch or any
``dev-*`` version string for this package.

Recommended root ``composer.json`` settings:

.. code-block:: json

   {
       "minimum-stability": "stable",
       "prefer-stable": true,
       "require": {
           "nitsan/ns-t3af": "^1.1"
       }
   }

If an audit or ``composer.lock`` review shows a dev branch reference, pin
``^1.1`` explicitly and refresh the lock:

.. code-block:: bash

   composer update nitsan/ns-t3af --with-dependencies

Verify the lock entry lists a ``1.1.x`` version and a tag commit reference,
not ``dev-dep/...``.

Local monorepo development may use path repositories with ``@dev``; that is
fine for development only. Production deployments should install from Packagist
tags.

Next steps
==========

Open :guilabel:`AI Foundation > AI Providers` to connect at least one provider,
then review :ref:`Configuration <configuration>`.