diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst index 6a1432b8..c2e66cb8 100644 --- a/Documentation/Installation/Index.rst +++ b/Documentation/Installation/Index.rst @@ -1,23 +1,35 @@ +:navigation-title: Installation + .. include:: /Includes.rst.txt +.. _installation_index: -.. index:: installation +===================================== +Prepare / Install local TYPO3 project +===================================== -.. _installation_index: +Setting up your local TYPO3 project requires a few simple steps. +This chapter will guide you through preparing your development environment, +installing TYPO3, and getting ready to build your first website. + +The rest of the Getting Started guide assumes that TYPO3 has been installed locally +using DDEV and Composer, as described here. -============ -Installation -============ +If you prefer a to use a different installation method (for example, manual +installation on a server), see the full +`TYPO3 installation guide `_. .. toctree:: :hidden: :titlesonly: - SystemRequirements/Index - Version + UsingDdev Install + Setup + Version + Updates/Index DeployTYPO3 ApplicationContext - Updates/Index + SystemRequirements/Index .. card-grid:: :columns: 1 @@ -26,41 +38,39 @@ Installation :class: pb-4 :card-height: 100 - .. card:: :ref:`System requirements ` + .. card:: :ref:`Using DDEV ` - System requirements for the host operating system, including its web - server and database and how they should be configured prior to - installation. + Learn how to install, update, and manage DDEV to run your TYPO3 + projects locally. - .. card:: :ref:`Version ` + .. card:: :ref:`Installing TYPO3 with DDEV ` - This chapter helps you choose the best TYPO3 version to start with and - provides resources for getting it. + Follow a quick and simple guide to install TYPO3 locally using DDEV, + Docker, and Composer. - .. card:: :ref:`Installing TYPO3 ` + .. card:: :ref:`Setting up TYPO3 after installation ` - This is a step-by-step guide detailing how to install TYPO3 for local - development using DDEV, Docker and Composer. + Complete TYPO3 setup by creating an admin user and configuring + initial options. - .. card:: :ref:`TYPO3 Updates ` + .. card:: :ref:`Choosing a TYPO3 version ` - Here we explain the cycle of TYPO3 updates, and show you why and when - a TYPO3 update is useful. + Find out which TYPO3 version to start with and where to get it. - .. card:: :ref:`Deploying TYPO3 ` + .. card:: :ref:`Keeping TYPO3 up to date ` - After you have installed TYPO3 locally, learn how to move your result - to a web server. + Learn about TYPO3 update cycles and how to keep your installation secure + and up to date. - .. card:: :ref:`Application context ` + .. card:: :ref:`Deploying TYPO3 to a server ` - Use the TYPO3 application context to manage settings for - development and production. + Learn how to move your TYPO3 project from your local DDEV environment + to a live web server. .. _installation_advanced: Advanced installation topics -============================ +============================= .. card-grid:: :columns: 1 @@ -69,7 +79,17 @@ Advanced installation topics :class: pb-4 :card-height: 100 - .. card:: :ref:`Tuning TYPO3 ` + .. card:: :ref:`Application context ` + + Use the TYPO3 application context to manage different settings for + development, testing, and production. + + .. card:: `System Requirements `_ + + If you want to install TYPO3 manually or deploy to a production server, check + the full system requirements for PHP, database, and web server. + + .. card:: `Tuning TYPO3 `_ - This chapter in TYPO3 Explained contains information on how to configure and optimize the - infrastructure running TYPO3. + Learn how to configure, optimize, and fine-tune the infrastructure + running TYPO3 for better performance and scalability. diff --git a/Documentation/Installation/Install.rst b/Documentation/Installation/Install.rst index 9e8b9420..3f55380e 100644 --- a/Documentation/Installation/Install.rst +++ b/Documentation/Installation/Install.rst @@ -3,195 +3,169 @@ .. index:: installation, deployment, requirements .. _install: -.. _install-access-typo3-via-a-web-browser: -.. _installation-ddev-tutorial: ========================== Installing TYPO3 with DDEV ========================== -This is a step-by-step guide detailing how to install TYPO3 using DDEV, Docker and Composer. +This guide provides step-by-step instructions for installing TYPO3 using DDEV +and Composer. -DDEV is used for local development only. +If DDEV is not yet installed on your local machine, see +`Installing and using DDEV `_. -.. youtube:: HW7J3G1SqZw - -.. note:: - Like TYPO3, DDEV is open source software that exists because of the generosity of community members and sponsors. Read more about `how to support DDEV `__. +DDEV is intended for local development only. +To deploy your TYPO3 site to a production server, see: +`Deploying TYPO3 `_. -Pre-Installation Checklist --------------------------- +Throughout the Getting Started Tutorial, we assume that you are running TYPO3 +locally with DDEV and have installed it using Composer. -#. **Install Docker** - Visit `docker.com `__ to download and install the recommended version of Docker for your operating system. +For an overview of alternative installation methods, see the +`TYPO3 installation overview in the TYPO3 Explained manual `_. -#. **Install DDEV** - Follow the `DDEV installation guide `__ to install DDEV. +.. contents:: Table of contents -DDEV and Docker need to be installed on your local machine before TYPO3 can be installed. If you need help installing DDEV, support can be found on the `DDEV Discord server `__. +.. _install-quick: -Create the Installation Directory ---------------------------------- +Quick Start: TYPO3 Installation with DDEV +========================================== -Create an empty directory to install TYPO3 in and then change into that directory: +The following commands will create a new TYPO3 project, initialize DDEV, install +TYPO3 via Composer, and run the setup. Copy and paste them into your terminal. .. code-block:: bash - mkdir t3example - cd t3example + # Create project directory + mkdir my_project && cd my_project -Create a new DDEV Project -------------------------- + # Initialize DDEV project + ddev config --php-version 8.4 --docroot public --project-type typo3 -The `ddev config` command will prompt for information about your project. TYPO3 is in the list -of preconfigured projects. + # Start DDEV + ddev start -.. code-block:: bash + # Install TYPO3 via Composer + ddev composer create "typo3/cms-base-distribution:^13" - ddev config --php-version 8.3 --docroot public --project-type typo3 + # Run TYPO3 CLI setup (database credentials are pre-filled) + ddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db -Docroot Location - Is the folder containing files that have to be reached by - the webserver. It contains the vital entry point :file:`index.php`. The folder is commonly called :file:`public`. + # Open the Backend login in a browser + ddev launch /typo3/ -Project Type - Should always be "typo3" +Next steps: `TYPO3 setup on first installation `_ .. note:: - The PHP version (:yaml:`php_version`) should be set manually to the required - version in :file:`.ddev/config.yaml`. + The directory that you run these commands in must be empty. + Do not initialize Git or open the folder in an IDE before running the + commands, as these may create files in the directory (for example hidden files). -Start the project ------------------ +.. _installation-ddev-tutorial: -.. code-block:: bash +Step-by-step: TYPO3 Installation with DDEV +========================================== - ddev start +.. _installation-video: -The webserver is now running but TYPO3 is not yet installed. +Video: Installing TYPO3 with DDEV +---------------------------------- -Install TYPO3 -------------- +The video demonstrates how to install TYPO3 v11 LTS with DDEV. -.. code-block:: bash +Although TYPO3 v11 is outdated, the installation process is largely +the same for newer versions. - ddev composer create "typo3/cms-base-distribution:^13" +.. youtube:: HW7J3G1SqZw -You now have a **Composer-based TYPO3 installation**. +.. _installation-empty-directory: -.. note:: - The command above installs a typical set of functionality. +Create the installation directory +---------------------------------- - The official `Composer Helper `__ - at Get TYPO3 supports you to generate commands for a full TYPO3 installation - with all optional system extensions included. +Create an empty directory for your TYPO3 project and change into it: -Run the Installation Setup Tool -------------------------------- +.. code-block:: bash -Setup TYPO3 in the console -~~~~~~~~~~~~~~~~~~~~~~~~~~ + mkdir my_project + cd my_project -.. versionadded:: 12.1 - Starting with TYPO3 12.1 a new CLI command `setup` is introduced as - an alternative to the existing GUI-based web installer. +.. note:: + The directory where you run the following commands must be empty. -Interactive / guided setup (questions/answers): + Do not initialize Git or open the folder in an IDE before running the + commands, as these may create files in the directory (for example hidden files). -.. code-block:: bash +.. _installation-ddev-project: - ddev typo3 setup +Create a New DDEV Project +-------------------------- -When prompted give the following answers to work with the default DDEV configuration: +Initialize a new DDEV project. The ``ddev config`` command will prompt you for details of your setup. +TYPO3 is included in the list of preconfigured project types. .. code-block:: bash - Which web server is used? - > other - - Database driver? - > mysqli - - Enter the database "username" [default: db] ? db + ddev config --php-version 8.4 --docroot public --project-type typo3 - Enter the database "password" ? db +Docroot Location + The docroot is the folder containing the files accessible to the webserver, + including the entry point :file:`index.php`. It is commonly named `public`. - Enter the database "port" [default: 3306] ? 3306 + Do not change the docroot during this installation process. You + can change it later if necessary, however most guides assume your docroot is + called `public`. - Enter the database "host" [default: db] ? db +Project Type + Always set the project type to `typo3`. - Select which database to use: - > db +.. _installation-ddev-start: -Setup TYPO3 with the 1,2,3 Install Tool in the browser -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Start the DDEV +-------------- -Create a file called :file:`FIRST_INSTALL` in your webroot +Start the DDEV project: .. code-block:: bash - ddev exec touch public/FIRST_INSTALL + ddev start -Open the installer +The webserver environment is now running, but TYPO3 is not yet installed. -.. code-block:: bash +.. _installation-typo3: - ddev launch /typo3/install.php +Install TYPO3 +------------- -Go to the TYPO3 backend: +Install TYPO3 using Composer: .. code-block:: bash - ddev launch /typo3 - -And login with the credentials you just provided. - - -Managing the Database ---------------------- - -:bash:`ddev start` automatically created a database for -you. DDEV also created the file :file:`config/system/additional.php` -in which it configured the database credentials for you. - -Many database browsers, including phpMyAdmin, are available to let you browse the database, see `Database GUIs `__ - -Sending E-Mail --------------- - -DDEV creates configuration in :file:`config/system/additional.php` -to capture sent mails. You can see what mails have been sent here: - -.. code-block:: bash + ddev composer create "typo3/cms-base-distribution:^13" - ddev launch -m +You now have a **Composer-based TYPO3 installation**. -Stopping a DDEV Instance ------------------------- +Directory structure after composer installation +----------------------------------------------- -If you want to stop all projects from running you can call: +At this point, your project folder should contain the following files and directories: .. code-block:: bash - ddev poweroff - -The projects will stay configured and databases will be persisted. - -Deleting a DDEV Instance ------------------------- - -If you want to delete the project you just created you can remove it by -calling the following command in your new projects root folder: - -.. code-block:: bash + ~/projects/typo3/sites/my_project$ ls -a + composer.json composer.lock config .ddev .gitignore LICENSE packages public README.md vendor - ddev delete --omit-snapshot +Additional folders like :directory:`var` and subfolders like +:directory:`config/sites` will be created during the setup process. -This will remove all containers from the project and delete the database. +.. _installation-setup: -Afterwards you can safely delete the project's root folder. +Next steps: Setup TYPO3 +----------------------- -DDEV Documentation ------------------- +At this point, important files and folders are still missing, and your database +does not yet contain any tables. -You will want to visit `DDEV's documentation `_, -which also has a `TYPO3 Quick Start `_ -which parallels this one. +All of these will be created during the setup process. +For detailed instructions, see: +`TYPO3 setup on first installation `_ diff --git a/Documentation/Installation/Setup.rst b/Documentation/Installation/Setup.rst new file mode 100644 index 00000000..2469e0b8 --- /dev/null +++ b/Documentation/Installation/Setup.rst @@ -0,0 +1,95 @@ +:navigation-title: Setup + +.. include:: /Includes.rst.txt +.. _typo3-setup: + +================================= +TYPO3 setup on first installation +================================= + +You can set up TYPO3 either via a console command or by using the web-based +Install Tool. + +.. contents:: + :local: + +.. _typo3-setup-console: + +Set up TYPO3 using the console +=============================== + +.. versionadded:: 12.1 + Starting with TYPO3 12.1, a new CLI command `typo3 setup` is available + as an alternative to the traditional web-based installer. + +To perform an interactive guided setup, run: + +.. code-block:: bash + + # Run TYPO3 CLI setup (database credentials are pre-filled) + ddev typo3 setup --server-type=other --driver=mysqli --host=db --port=3306 --dbname=db --username=db --password=db + +When prompted, provide the following answers to match the default DDEV +configuration: + +.. code-block:: text + + Admin username (user will be "system maintainer") ? j.doe + Admin user and installer password ? + Admin user email ? j.doe@example.org + Give your project a name [default: New TYPO3 Project] ? My Project + Create a basic site? Please enter a URL [default: no] https://my-project.ddev.site + ✓ Congratulations - TYPO3 Setup is done. + +.. _install-access-typo3-via-a-web-browser: + +Set up TYPO3 using the web installer (1-2-3 install tool) +========================================================= + +Alternatively, you can use the web-based Install Tool to set up TYPO3. + +1. Create a file named :file:`FIRST_INSTALL` in your webroot: + + .. code-block:: bash + + ddev exec touch public/FIRST_INSTALL + +2. Open the TYPO3 installer in your browser: + + .. code-block:: bash + + ddev launch /typo3/install.php + +3. After completing the setup, access the TYPO3 backend: + + .. code-block:: bash + + ddev launch /typo3 + +Log in using the credentials you just created during the setup process. + +.. _typo3-setup-application context: + +Set the application context for local development +================================================== + +After completing the setup, TYPO3 will run in the "Production" application +context by default. + +For local development, it is recommended to switch to the "Development/DDEV" +context for better error reporting, debugging features, and developer-friendly +features. + + Edit your :file:`.ddev/config.yaml` and add: + +.. code-block:: yaml + :caption: .ddev/config.yaml + + environment: + - TYPO3_CONTEXT=Development/DDEV + +Restart DDEV to apply the changes: + +.. code-block:: bash + + ddev restart diff --git a/Documentation/Installation/UsingDdev.rst b/Documentation/Installation/UsingDdev.rst new file mode 100644 index 00000000..d5c820c5 --- /dev/null +++ b/Documentation/Installation/UsingDdev.rst @@ -0,0 +1,165 @@ +:navigation-title: Using DDEV + +.. include:: /Includes.rst.txt +.. _ddev: + +========================= +Installing and using DDEV +========================= + +DDEV is a powerful tool for local TYPO3 development. It automates +the setup of PHP, database, webserver, and other services using Docker, making +local development easy, fast, and consistent across platforms. + +This guide assumes that you are setting up TYPO3 locally using DDEV. +For deploying TYPO3 to a live server, see +`Deploying TYPO3 `_. + +Some hosting providers also host DDEV projects, +allowing you to develop locally and deploy seamlessly. + +.. note:: + Like TYPO3, DDEV is open source software that only exists due to the + generosity of community members and sponsors. Read more about + `how to support DDEV `__. + +.. contents:: Table of contents + +.. _ddev-install-docker: + +Install Docker +============== + +Docker is required to run DDEV containers. + +- Visit `docker.com `__ and download the latest + version for your operating system. +- Follow the installation instructions for your platform (Windows, macOS, or + Linux). + +.. _ddev-install-ddev: + +Install DDEV +============ + +Once Docker is running, install DDEV by following the official installation +instructions: + +`Installing DDEV `_ + +This page covers installation for macOS, Linux, Windows, and WSL, and is kept +up-to-date. + +.. _ddev-check-installation: + +Check your DDEV installation +============================ + +After installing, verify that Docker and DDEV are available: + +.. code-block:: bash + + docker --version + ddev version + +If both commands return version information, installation was successful. + +.. note:: + If you encounter problems installing DDEV, support is available via the + `DDEV Discord server `__. + +When DDEV is up and running, you can continue with +`Installing TYPO3 with DDEV `_. + +.. _ddev-update: + +Update DDEV +=========== + +DDEV releases frequent updates with new features, bug fixes, and improvements. +It is recommended to keep DDEV up to date. + +For instructions on how to update DDEV on your operating system, see the official +`DDEV Upgrade Guide +`_. + +After updating, verify the installed version: + +.. code-block:: bash + + ddev version + +.. _ddev-managing-database: + +Managing the database +====================== + +Running :bash:`ddev start` automatically creates a database for you. +DDEV also creates the file :file:`config/system/additional.php`, containing the +database credentials. + +You can access your database using any local database client. + +On Windows, you can quickly open the database in HeidiSQL: + +.. code-block:: bash + + ddev heidisql + +Other popular database clients include TablePlus, Sequel Ace, and DBeaver. + +For more details, see the DDEV documentation on +`Database GUIs +`__. + +.. _ddev-sending-email: + +Sending emails +============== + +DDEV captures outgoing mails and stores them for review. +You can view sent emails with: + +.. code-block:: bash + + ddev launch -m + +.. _ddev-stopping-instance: + +Stopping a DDEV instance +======================== + +If you want to stop all running DDEV projects, run: + +.. code-block:: bash + + ddev poweroff + +The projects will remain configured and databases will be persisted. + +.. _ddev-deleting-instance: + +Deleting a DDEV instance +======================== + +If you want to delete the project you created, run the following command inside +your project root folder: + +.. code-block:: bash + + ddev delete --omit-snapshot + +This removes all containers for the project and deletes the database. + +Afterwards you can safely delete the project root folder manually if needed. + +.. _ddev-documentation: + +DDEV documentation +=================== + +You can find detailed documentation at +`DDEV Documentation `_. +There is also a `TYPO3 Quick Start +`_ that +parallels this guide.