.. _installation:

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

To install and configure the headless extension, follow these detailed steps. First, ensure TYPO3 is installed and running (refer to :ref:`t3install:start` for the standard TYPO3 installation process). Once TYPO3 is operational, proceed with the following steps to install the headless extension:

1. **Install and activate the extension**:
   - Using Composer (recommended): Run the following command in your terminal:
     ```
     composer require friendsoftypo3/headless
     ```
   - Alternatively, use the Extension Manager with the extension key `headless`.

2. **Create a new root page**:
   - This page will serve as the JSON API endpoint for your application.
   - Open the TYPO3 backend, navigate to the page tree, and create a new page at the root level. Name this page appropriately (e.g., "API Root").

   .. figure:: ../Images/Installation/RootPage.png
      :alt: Root page for the API endpoint
      :class: with-shadow

3. **Create a new root template**:
   - In the TYPO3 backend, go to *Site Management* > *TypoScript* (or *Web* > *Template* for versions prior to v12).
   - Add the `headless` static template by including it in the "Include static (from extensions)" section.
   - Save your changes. You should now be able to see the JSON output when displaying the page.

4. **Create a site configuration**:
   - The site configuration is essential as it defines the URL that will serve as the API endpoint for the frontend application.
   - In TYPO3 v10 and above, an autogenerated site configuration may already exist. You can rename and configure this site to suit your needs.

   .. important::

      It is recommended to use a dedicated URL like `https://api.mydomain.org` for the endpoint. Using URLs such as `https://mydomain.org/api` might lead to unexpected behaviors.