Docker + TYPO3 (Template)

The files in this repository are meant to be used as the starting point for a new TYPO3 project based on the Tollwerk Docker images. Apart from a working Docker setup, only two files are necessary to kickstart a new project following this setup:

• docker-compose.yml to download and initialize the Docker images. The tollwerk/typo3 image is kinda "self-extracting" and will take care of the installation process.

• .env.example which will serve as template for a project specific environment file (.env) you will have to craft before starting the Docker containers for the first time.

Project kick-off

Before you can start working on your project on potentially many development machines, you have to create and configure an original instance which will also be used for your initial Git commits.

Important

This has to be done on one of the workstations which will also be used for development purposes later on.

On the command line of your machine, change to the directory where your project should live and create a shallow clone of this repository (replace <new_project_name> accordingly):

1. Navigate to your project’s parent directory.

   cd /path/to/project/parent

2. Create a shallow clone of this repository (replace <new_project_name>).

   git clone --depth=1 https://github.com/tollwerk/docker-template-typo3.git <new_project_name>

3. Change to the new project directory:

   cd <new_project_name>

4. Remove the tracking link to the original template repository.

   git remote remove origin

5. Reset ownership to yourself.

   git commit --amend --reset-author -m "Initial Commit"

Configuration & installation

1. Copy the .env.example to .env and edit the environment variables inside to match your project requirements. For this purpose, you may open the project in your favourite editor / IDE for the first time.

   Important

   If you’re planning to run a dedicated instance on a (non-Docker) preview server (Tollwerk internal), it’s important to use the database credentials that are used on the preview server. Set the following environment variables accordingly: TYPO3_INSTALL_DB_USER TYPO3_INSTALL_DB_PASSWORD TYPO3_INSTALL_DB_DBNAME MYSQL_DATABASE MYSQL_USER MYSQL_PASSWORD PMA_USER PMA_PASSWORD The database host (TYPO3_INSTALL_DB_HOST, PMA_HOST) is always set to mysql

2. Let Docker bring up the containers and install TYPO3 and other components:

   docker-compose up

   Caution

   Please be patient during the first start of the the Docker containers. There’s a lot composer and other tools hav to install at this stage. You may use the time for setting up the two remote Git repositories that are required later on.

3. Install the required Node.js packages by running the setup npm script:

   npm run setup

   Tip	Using Git bash for running this command might cause troubles with Git submodules. Use a different command line or your IDE to avoid this problem.

Dynamic production state updates

As soon as Docker has launched for the first time, a fresh TYPO3 instance should have been installed to your file system. In order to have updateable production states (data files and database contents), the fileadmin directory of your TYPO3 instance must be put under the control of a separate Git repository which is later included as a submodule of the main repository.

Tip	The following instructions use Linux commands. On windows workstations you may use the Git Bash that comes with your Git installation to execute these commands.

1. On your workstation, from the command line, change to the fileadmin directory of your original instance:

   cd public/fileadmin

2. Create the following directory / file structure (you may also do this with the help of your regular file system tools and favourite editor / IDE):

   ├── .githooks
   │   └── post-merge
   ├── .gitattributes
   └── .gitignore

   The post-merge hook will watch out for a file named database.sql in the root directory of the repository which should contain a database dump corresponding to the file contents in the directory. Whenever the dump changes, an indicator file named database.IMPORT_RESET will be created. During startup, the TYPO3 docker container will look for the presence of this file (public/fileadmin/database.IMPORT_RESET) and — if present — replace the database with the contents of database.sql (and remove the indicator file afterwards).

   .githooks/post-merge

   #!/usr/bin/env bash
   
   # git hook to run a command after `git pull` if a specified file was changed
   # Run `chmod +x post-merge` to make it executable then put it into `.githooks/`.
   
   changed_files="$(git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD)"
   
   check_run() {
   	echo "$changed_files" | grep --quiet "$1" && eval "$2"
   }
   
   # Drop update indicators for database
   check_run database.sql "touch database.IMPORT_RESET"

   Tip	You may copy the hook file of the same name from the main repository and just change the last two lines.

   You should protect binary files from being treated as text files by adding .gitattributes:

   .gitattributes

   # Path-based git attributes
   # https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html
   # Auto detect text files and perform LF normalization
   * text eol=lf
   
   # (binary is a macro for -text -diff)
   *.br binary
   *.png binary
   *.jpg binary
   *.jpeg binary
   *.gif binary
   *.gz binary
   *.ico binary
   *.mov binary
   *.mp4 binary
   *.mp3 binary
   *.flv binary
   *.fla binary
   *.swf binary
   *.gz binary
   *.zip binary
   *.7z binary
   *.ttf binary
   *.eot binary
   *.woff binary
   *.woff2 binary
   *.pyc binary
   *.pdf binary
   
   # Ignore all test and documentation with "export-ignore".
   /.gitattributes export-ignore
   /.gitignore export-ignore
   /database.IMPORT_RESET
   /database.sql

   Temporary files (e.g. images) as well as the database update indicator should never go to the repository, so add these lines to your .gitignore:

   .gitignore

   _temp_
   _processed_
   /database.IMPORT_RESET

3. Create a new online repository for your project’s fileadmin. This repository is referred to as the Data Repository.

4. Copy the unique repository URL (SSH) to your clipboard.

5. Make the Git hook executable, initialize the repository (replace the origin path with your clipboard content / the Data Repository URL) and register the custom hook directory:

   # Change to the fileadmin directory
   chmod +x .githooks/post-merge
   git init
   git remote add origin <new_data_repo_URL>
   git config --local core.hooksPath .githooks/

6. Commit and push to a branch (usually main).

   git add .
   git commit -m "Initial commit"
   git push -u origin main

Push to a remote repository

1. Create a new online repository for your project. This repository is referred to as the Project Repository.

2. Copy the unique repository URL (SSH) to your clipboard.

3. On your workstation, from the command line, change to the root directory of your original instance, add the remote tracking information for the project repository and register the fileadmin repository (Data Repository) as a submodule.

   git remote add origin <new_project_repo_URL>
   git submodule add <new_data_repo_URL> public/fileadmin

4. Empty this very README.adoc file and adapt it you your needs matching the new project’s requirements.

5. Commit and push to a branch (usually main).

   git add .
   git commit -m "Initial commit"
   git push -u origin main

TYPO3 setup

In order to finalize the initial TYPO3 setup you need to perform the following steps. Please make sure that the Docker containers are running (docker compose up).

Note	The following instructions intentionally don’t include screenshots to keep them text-only and as lean as possible.

1. Log into your TYPO3 instance by visiting https://localhost/typo3 with your browser and using the credentials found in your .env file (defaulting to admin / sEcr3tWith8CharsMin!).

2. Edit the main TypoScript template of your site using the Template module:

   • Replace the default Setup code with the following (adapt tw_demo to your project extension key as per .env configuration):

     <INCLUDE_TYPOSCRIPT: source="FILE:EXT:tw_demo/Configuration/TypoScript/Main/10_main.typoscript">
     config.contentObjectExceptionHandler = 0

   • Include the TypoScript setup of the tw_base and tw_demo (adapt to your needs) extensions (and potentially add tw_componentlibrary, form etc.).

   • Empty the default template Note (or adapt to your needs).

3. Pick the Standard backend layout for the root page add the tw_base and tw_demo (adapt to your needs) extension TSConfig under Include static Page TSconfig (from extensions).

You’re almost ready for development now. In a final step, you should push this blank TYPO3 state to the data repository so that others can make use of it.

1. From the command line, let the web Docker container create a dump of the current database state into the fileadmin directory.

   docker exec web sh -c "mysqldump -h mysql -u user --password=password db > /www/public/fileadmin/database.sql"

2. From your project instance’s root directory, commit and push the current production state to the data repository:

   cd public/fileadmin
   git add .
   git commit -m "Add initial database state"

Start developing

You’re now ready to checkout the project repository on other workstations and start developing. Here are some important things to keep in mind:

• Whenever you pick up development work (e.g. in the morning), start by updating your local repositories from the upstream origin. This is important for both the project and the data repository.

• Never push to the data repository. Only an authorized preview / demo instance should be allowed to do so, and this should be enforced by according Git privileges.

• Whenever you see the files composer.NEEDS_UPDATE or package.NEEDS_UPDATE in your root directory, it’s a sign that either the composer or Node.js packages need to be updated. Do this by running composer install respectively npm install from the command line in your instance root directory.

• If you feel like (manually) resetting the database to the latest "official" state, create an (empty) database.INSTALL_RESET file in your fileadmin directory and restart the web Docker container.