.. include:: /Includes.rst.txt

.. _restore:

=======
Restore
=======

.. figure:: /Images/screenshot-restore.png
   :alt: Restore confirmation dialog warning that the current installation will be overwritten
   :class: with-shadow
   :zoom: lightbox

   Restoring from the UI prepares the installer in the document root and
   switches the site into restore mode.

.. _restore-target-server:

Target server (installer)
=========================

1. Copy the downloaded :file:`.t3vault.tar` (and installer files if provided) to
   the target machine.
2. Run the installer / follow the UI import flow in a fresh T3Vault standalone
   app on the target.
3. Enter the **same backup encryption password** used when the backup was
   created.
4. Choose the **target layout** if it differs from the backup source
   (:file:`MANIFEST.json` records Composer vs. classic):

   * Restore a **Composer** backup as **classic/legacy** (document root) when
     the target host has no Composer-based deploy.
   * Restore a **classic** backup as **Composer** when you want
     :file:`config/` + :file:`public/` (or a DDEV project).

5. Complete Composer install / TYPO3 setup as required by the chosen target
   layout.

.. _restore-installer-https:

Transport security
------------------

The installer refuses to run over plain HTTP, because the restore transfers the
backup password and the database credentials. Accepted as secure: real HTTPS,
HTTPS terminated by a proxy listed in ``T3VAULT_TRUSTED_PROXIES``, or a client on
the loopback interface — for example through an SSH tunnel:

.. code-block:: bash

   ssh -L 8443:localhost:80 user@target
   # then open http://127.0.0.1:8443/installer.php

Only if the network is demonstrably trusted, the requirement can be waived by
creating the file :file:`.t3vault-allow-insecure` next to the installer (or by
setting ``T3VAULT_ALLOW_INSECURE=1``). The environment check then shows a
warning for the connection instead of a green check.

The step **Write configuration** additionally accepts an optional
``encryptionKey``. Leave it empty to have a fresh key generated; supply the key
of the original installation if hashes stored in the database (e.g. install tool
secrets) have to stay valid.

.. _restore-site-base-url:

Site base URL
-------------

If you enter a **Site base URL**, the installer updates a single primary site
under :file:`config/sites/*/config.yaml` (or classic :file:`typo3conf/sites/`) as follows:

* the primary site is the one with ``rootPageId: 1``, otherwise the lowest
  ``rootPageId``;
* only that site’s top-level ``base`` is set to the new URL;
* existing ``baseVariants`` (production, staging, old DDEV hosts, …) stay as they
  are;
* for ``*.ddev.site`` hosts, at most one ``Development/DDEV`` variant is added or
  refreshed;
* absolute language bases such as ``https://en.example.com/`` become a path on the
  new host (``https://recover.ddev.site/en/``).

Leave the field empty to skip site-config changes entirely.

If the target host is **already defined** in any site’s top-level ``base`` or
``baseVariants``, the installer leaves all site URLs unchanged (restore onto a
known domain).

**Multi-site:** other sites keep their original bases and are not reachable on
the recover host until you add hostnames (for example DDEV
``additional_hostnames``) or map them manually.

.. _restore-ddev:

DDEV (local)
============

Use **Download → DDEV project** or the scripts inside the TAR
(:file:`t3vault-ddev.sh`, :file:`t3vault-ddev.php`, :file:`DDEV.md`).

Typical flow:

1. Run the script; it loads the archive (or uses a local :file:`.t3vault.tar`).
2. Enter the backup password.
3. The script unpacks AES ZIPs, converts the layout toward Composer if the
   source was classic, writes :file:`.ddev/config.yaml` from environment
   metadata, starts DDEV, imports the database, and runs ``composer install``.
   (The web installer also supports the opposite direction: Composer →
   classic/legacy.)

.. _restore-verify-first:

Verify before restore
=====================

Before trusting an archive from untrusted storage, verify that it was not
modified after sealing (see :ref:`integrity-how-to-verify`):

.. code-block:: bash

   php t3vault-verify.phar /path/to/backup_dir

Optionally confirm the OpenTimestamps seal with :ref:`opentimestamps-manual`.