Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Add quick start chapter #886

Draft
wants to merge 3 commits into
base: master
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions Build/render-docs.bat
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,3 @@
pushd %~dp0
docker-compose --file render-docs.yml run --rm t3docmake
popd

echo Rendering has done, find the results in .build/Documentation
6 changes: 2 additions & 4 deletions Build/render-docs.sh
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
#!/bin/bash

pushd `dirname "$0"` >/dev/null
pushd `dirname "$0"`
docker-compose --file render-docs.yml run --rm t3docmake
popd >/dev/null

echo "Rendering has done, find the results in .build/Documentation"
popd
2 changes: 1 addition & 1 deletion Build/render-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ services:
command: makehtml
volumes:
- ../:/PROJECT:ro
- ../.build/Documentation:/RESULT
- ../.build/Documentation-GENERATED-temp:/RESULT
6 changes: 5 additions & 1 deletion Documentation/Includes.txt
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. ==================================================
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
Expand All @@ -19,3 +19,7 @@
.. role:: php(code)

.. highlight:: php

.. role:: composer(code)

.. role:: button(code)
5 changes: 3 additions & 2 deletions Documentation/Index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Bootstrap Package
2014

:Author:
Benjamin Kott
Benjamin Kott and contributors

:Email:
[email protected]
Expand All @@ -58,4 +58,5 @@ Bootstrap Package

Introduction/Index
Configuration/Index
AdministratorManual/Index
AdministratorManual/Index
QuickStart/Index
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Documentation/QuickStart/Images/Backend/Login.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Documentation/QuickStart/Images/ProjectFolder.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Documentation/QuickStart/Images/Setup/Step1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Documentation/QuickStart/Images/Setup/Step4.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Documentation/QuickStart/Images/Setup/Step5.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
43 changes: 43 additions & 0 deletions Documentation/QuickStart/Index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../Includes.txt


========================
Quick Start from Scratch
========================

This guide explains to setup your new TYPO3 project with Bootstrap Package and a
Sitepackage from scratch with the help of DDEV Local on your local computer.
Once you have finished you can deploy it to a hoster of your choice.


System Requirements
===================

Make sure you have the following components installed before you continue:

* `DDEV Local and Docker <https://ddev.readthedocs.io/en/stable/>`_
* `Git <https://git-scm.com/>`_ or similar software configuration management,
Git is required on Windows to successfuly run DDEV and used as reference in
this guide
* Editor of your choice like `Visual Studio Code <https://code.visualstudio.com/Download>`_
or `PhpStorm <https://www.jetbrains.com/de-de/phpstorm/download/>`_

Once you have successfuly installed the previous mentioned components your
project will be setup and ready to use within minutes.


Overview
========

.. toctree::
:maxdepth: 5
:titlesonly:
:glob:

Preparation/Index
Sitepackage/Index
98 changes: 98 additions & 0 deletions Documentation/QuickStart/Preparation/Composer.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../../Includes.txt


==================
Configure Composer
==================


Now it's time to tell Composer which packages and TYPO3 extensions you like to
install and setup. The initial setup we have already done before with the
download of the TYPO3 Base Distribution.


TYPO3 Secure Web (optional)
===========================

To increase the security of your project you can simply use the
:composer:`helhum/typo3-secure-web` package.

.. code-block:: bash

ddev composer config extra.typo3/cms.root-dir private
ddev composer config extra.typo3/cms.web-dir public
ddev exec mkdir -p private/typo3conf
ddev exec ln -rs public/typo3conf/AdditionalConfiguration.php private/typo3conf/AdditionalConfiguration.php
ddev composer require "helhum/typo3-secure-web" --no-update

You also need to change the :file:`.gitignore` in your project root a little
bit. Just copy the lines starting with /public/... and replace **public** by
**private** but omit the last line with the
:file:`!/private/typo3conf/AdditionalConfiguration.php`. Finally it should look
similar to this one:

.. code-block:: json

.DS_Store
.idea
nbproject
/var/*
!/var/labels
/vendor
/public/*
!/public/.htaccess
!/public/typo3conf
/public/typo3conf/*
!/public/typo3conf/LocalConfiguration.php
!/public/typo3conf/AdditionalConfiguration.php
/private/*
!/private/.htaccess
!/private/typo3conf
/private/typo3conf/*
!/private/typo3conf/LocalConfiguration.php

More information can be found at the `TYPO3 Secure Web Github Repository <https://github.com/helhum/typo3-secure-web#readme>`_


Additional TYPO3 (Core) Extensions
==================================

You are free to add more packages, for core extensions head to the
`Composer Helper <https://get.typo3.org/misc/composer/helper>`_ and select the
desired packages, extensions can be found at the
`TYPO3 Extension Repository <https://extensions.typo3.org/>`_. Make sure you
always add the :composer:`--no-update` option to avoid version conflicts
later.

.. code-block:: bash

ddev composer require "typo3/cms-lowlevel:^10.4"
ddev composer require georgringer/news

Be careful when installing **Distributions**, they may conflict with the
**Sitepackage**. So consider to install a **Distribution** only and adding
the **Sitepackage** later.


Install the Packages
====================

Once you have finished adding more packages run the following commands to
start the installation process:

.. code-block:: bash

ddev composer install
ddev composer install

Yes, run the same command twice, there may be issues with the creation of
symlinks in the web container and a second run solves it! If you see your
**Sitepackage** in the lines of activated packages you can also omit the
second run but it does not hurt anyway.

Your project is now installed and ready to setup.
23 changes: 23 additions & 0 deletions Documentation/QuickStart/Preparation/Git.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../../Includes.txt


==============================================
Initialize the local Git Repository (optional)
==============================================

It is recommended you manage your project with version control system like
**Git** but there is no restriction, you can use your favorite one. This guide
will use **Git** in the examples.

.. code-block:: bash

git init

Your local repository is now setup and ready to use. Please head to the
`Git documentation <https://git-scm.com/doc>`_ to learn how to use **Git** for
your daily work.
31 changes: 31 additions & 0 deletions Documentation/QuickStart/Preparation/Index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../../Includes.txt


===========
Preparation
===========

Before you can start working on your new project some preparation steps are
required.


Overview
========

.. toctree::
:maxdepth: 5
:titlesonly:
:glob:

ProjectFolder
Sitepackage
Composer
InstallWizard
Git
Template
Page
68 changes: 68 additions & 0 deletions Documentation/QuickStart/Preparation/InstallWizard.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.

.. include:: ../../Includes.txt


===========
Setup TYPO3
===========

In this step your new TYPO3 instance will be setup with a initial
configuration. To gain access to the **TYPO3 Install Wizard** you need to
create the file :file:`FIRST_INSTALL` in the web server root directory:

.. code-block:: bash

ddev exec touch public/FIRST_INSTALL
ddev launch

With TYPO3 Secure Web use the following commands:

.. code-block:: bash

ddev exec touch private/FIRST_INSTALL
ddev launch

The last command will open the browser pointing to the **TYPO3 Install Wizard**
which is used for the initial setup of your project. Some steps are skipped
because various configurations like database credentials are already provided
by DDEV and you don't have to care about.


Step 1
======

.. figure:: ../Images/Setup/Step1.png
:width: 500px
:alt: TYPO3 Install Wizard Step 1
:class: with-border

Just click :button:`No problems detected, continue with installation` to
continue with the next step.


Step 2
======

.. figure:: ../Images/Setup/Step4.png
:width: 500px
:alt: TYPO3 Install Wizard Step 4
:class: with-border

Fill the form with the desired credentials for your administrative user and
click :button:`Continue` to head to the final step.


Step 3
======

.. figure:: ../Images/Setup/Step5.png
:width: 500px
:alt: TYPO3 Install Wizard Step 5
:class: with-border

Select :button:`Create empty starting page` and click
:button:`Open the TYPO3 Backend` to be redirected to the backend login page.
Loading