.. include:: /Includes.rst.txt

.. _installation:

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

.. _installation-composer:

Composer
========

The recommended install path is Composer. Require the package in your TYPO3
project (also on
`Packagist <https://packagist.org/packages/codemacher/t3vault>`_ and
`TER <https://extensions.typo3.org/extension/t3vault>`_):

.. code-block:: bash

   composer require codemacher/t3vault

T3Vault depends on ``codemacher/elephstamp`` (OpenTimestamps), which is pulled
in automatically from Packagist.

Provisioning of :file:`<web-dir>/t3vault` runs via
``typo3/cms-composer-installers`` (InstallerScripts) on
``composer install`` / ``update`` / ``dump-autoload``.

.. _installation-provisioning:

Standalone app provisioning
===========================

On every ``composer install`` / ``update`` / ``dump-autoload``,
T3Vault copies the standalone app into :file:`<web-dir>/t3vault`.

* The configuration (:file:`<project>/var/t3vault/config.local.php` and
  :file:`backup.password.php`, outside the web root) is **never** overwritten;
  legacy copies inside :file:`<web-dir>/t3vault/` are migrated automatically.
* Opening the T3Vault backend module also re-syncs that folder as a fallback.

After ``composer remove codemacher/t3vault``, delete the leftover web copy
manually if it is still present:

.. code-block:: bash

   rm -rf public/t3vault

.. _installation-activation:

Activation
==========

1. Activate the extension in the Extension Manager / Package Manager (Composer
   installs usually activate automatically).
2. Open **Admin Tools → T3Vault** (module path ``/module/tools/t3vault``;
   admin users only).
3. Set the **standalone password** when prompted (used for disaster
   recovery login outside the TYPO3 backend).
4. In the T3Vault UI settings, set a **backup encryption password**
   (minimum 8 characters) before creating the first backup.

.. important::

   Store the backup encryption password offline. Without it, encrypted ZIP
   parts cannot be restored. AES-ZIP does not hide file names or the directory
   tree — keep backups outside the web root.

.. _installation-webroot-hardening:

Web root hardening
==================

The standalone app is provisioned into the public web root
(:file:`<web-dir>/t3vault`). The configuration with all secrets lives outside
the web root (:file:`<project>/var/t3vault/`, see :ref:`configuration`), and so
does the ``ENABLE_T3VAULT`` marker (see :ref:`enable-file`); the app directory
still ships an Apache :file:`.htaccess` that protects legacy
:file:`config.local.php` copies, legacy marker files, the installer templates
(:file:`*.tpl`) and any backup artifacts, and restricts the :file:`Api/`
directory to :file:`Api/index.php`.

.. warning::

   :file:`.htaccess` files are ignored by **nginx** and **Caddy**. On those web
   servers you MUST replicate the rules in the server configuration, otherwise
   legacy :file:`config.local.php` copies, the installer templates and backup
   files become publicly downloadable.

nginx equivalent (place inside the relevant ``server`` block)::

   location ^~ /t3vault/ {
       # Protect legacy configuration/marker copies inside the web root.
       location ~ ^/t3vault/(config\.local\.php|ENABLE_T3VAULT)$ { deny all; }

       # The Api/ directory only exposes index.php – everything else
       # (framework classes, installer templates) is read from disk by PHP.
       location ~ ^/t3vault/Api/(?!index\.php)  { deny all; }

       # Never serve templates, logs, PHARs or backup artifacts as static files.
       location ~ ^/t3vault/.*\.(tpl|log|sql|gz|zip|tar|phar)$ { deny all; }

       # Security headers for the SPA shell (T3V-022). frame-ancestors does NOT
       # fall back to default-src and must be set explicitly; 'self' allows the
       # same-origin TYPO3 backend iframe. script-src is 'self' only (the shell
       # loads bootstrap.js instead of an inline block); style-src keeps
       # 'unsafe-inline' for MUI/Emotion's runtime styles.
       add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; font-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'self'" always;
       add_header Referrer-Policy "no-referrer" always;
       add_header X-Content-Type-Options "nosniff" always;
   }

For classic installations (project root equals the document root) the private
runtime directory :file:`var/t3vault/` (configuration, secrets, state) is
web-reachable and must be denied as well::

   location ^~ /var/t3vault/ { deny all; }

Additionally protect the backup target directory. The default
(:file:`<project-root>/var/t3vault/backups`) already lives outside
:file:`public/`; if you override ``backupBaseDir``, keep it outside the web
root.