Initialize git Repository

First please either create a new git repository or clone the existing repository for this project.

At a minimum we will need to create the following files in our repository:

{project_name}
│ .gitignore
│ LICENSE

./.gitignore

This file configures which files/folders should be ignored in the git repository. Since we're using our local setup for development, we need to exclude all development files (like fileadmin folder and the files generated by our composer setup).

.DS_Store
.idea
/vendor
/public/fileadmin
/public/typo3
/public/typo3conf/ext
/public/typo3conf/l10n
/public/typo3temp
/public/index.php
/public/uploads

./LICENSE

Unless requested otherwise - all our work is in the public domain.

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.

In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

For more information, please refer to <https://unlicense.org>

 

Clean up existing git repository

Move project specific extensions

Move project specific extensions (that can not be obtained via composer) to the ./packages folder.

Move LocalConfiguration.php and PackageStates.php

Move LocalConfiguration.php and PackageStates.php to ./public/typo3conf folder.

Move site configuration

Move all folders in typo3conf/sites to ./config/sites.

Move .htaccess

If specified, move the .htaccess file in the TYPO3 root to ./public folder.

Move fileadmin and uploads

If you want to develop locally, you can keep the uploads and fileadmin folders by moving them to the ./public folder. They will not get commited to git because of the .gitignore file.

Delete everything else

Delete everything else. Really! All other TYPO3 files will be gathered and set up by composer later.

Commit the changes

git commit .
git push

 

Configure Docker

To configure docker, we must edit the following files:

{project_name}
| docker-compose.yml
└─── docker
|  └─── typo3
|    |  Dockerfile
|  └─── database
|    |  Dockerfile

These files are in general identical for all our projects and can just be copy/pasted unless requested differently.

./docker-compose.yml

version: "3"
services:
  typo3:
    build: docker/typo3
    ports:
      - "80:80"
    volumes:
      - ./config:/var/www/html/config:Z
      - ./public:/var/www/html/public:Z
      - ./vendor:/var/www/html/vendor:Z
      - ./packages:/var/www/html/packages:Z
    environment:
      - TYPO3_CONTEXT=Development
      - HOSTNAME=localhost
      - APACHE_DOCUMENT_ROOT=/var/www/html/public
    external_links:
      - database:database
    networks:
      - backend
  composer:
    image: composer
    volumes:
      - .:/var/www/html:Z
    working_dir: /var/www/html
  database:
    build: docker/database
    command:
      - --character-set-server=utf8
      - --collation-server=utf8_unicode_ci
      - --default-authentication-plugin=mysql_native_password
    environment:
      - "MYSQL_USER=typo3"
      - "MYSQL_PASSWORD=typo3"
      - "MYSQL_DATABASE=typo3"
      - "MYSQL_ROOT_PASSWORD=rootpassword"
    networks:
      - backend
  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    external_links:
      - database:db
    ports:
      - "8080:80"
    networks:
      - backend
networks:
  backend:

docker/typo3/Dockerfile

FROM php:7.2-apache-stretch
LABEL maintainer="ext.dev <[email protected]>"

ENV APACHE_DOCUMENT_ROOT=/var/www/html/public
RUN sed -ri -e 's!/var/www/html!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/sites-available/*.conf
RUN sed -ri -e 's!/var/www/!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf

# Install TYPO3
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        wget \
# Configure PHP
        libxml2-dev libfreetype6-dev \
        libjpeg62-turbo-dev \
        libmcrypt-dev \
        libpng-dev \
        zlib1g-dev \
# Install required 3rd party tools
        graphicsmagick && \
# Configure extensions
    docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ && \
    docker-php-ext-install -j$(nproc) mysqli soap gd zip opcache intl xml && \
    echo 'always_populate_raw_post_data = -1\nmax_execution_time = 240\nmax_input_vars = 1500\nupload_max_filesize = 32M\npost_max_size = 32M\nmemory_limit = 512M' > /usr/local/etc/php/conf.d/typo3.ini && \
# Configure Apache as needed
    a2enmod rewrite && \
    a2enmod deflate && \
    apt-get clean && \
    apt-get -y purge \
        libxml2-dev libfreetype6-dev \
        libjpeg62-turbo-dev \
        libmcrypt-dev \
        libpng-dev \
        zlib1g-dev && \
    rm -rf /var/lib/apt/lists/* /usr/src/*

docker/database/Dockerfile

FROM mysql:5.7 
LABEL maintainer="ext.dev <[email protected]>" 
RUN echo 'sql_mode=ONLY_FULL_GROUP_BY,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION' >> /etc/mysql/mysql.conf.d/mysqld.cnf

 

Setting up composer

To configure composer we will need to create the following file structure

{project_name}
| composer.json
| composer.lock

The composer.lock file will get generated by composer - so we only have to create the composer.json file

./composer.json

{
    "require": {
        "typo3/minimal": "10.4",
        "typo3/cms-about": "^10.4",
        "typo3/cms-belog": "^10.4",
        "typo3/cms-beuser": "^10.4",
        "typo3/cms-fluid-styled-content": "^10.4",
        "typo3/cms-reports": "^10.4",
        "typo3/cms-rte-ckeditor": "^10.4",
        "typo3/cms-tstemplate": "^10.4",
        "typo3/cms-form": "^10.4",
        "typo3/cms-lowlevel": "^10.4"
    },
    "repositories": [
        {
            "type": "path",
            "url": "./packages/*"
        }
    ]
}

Make sure to require all extensions that this TYPO3 project uses. Details on how to identify the package name can be found here:
https://docs.typo3.org/m/typo3/guide-installation/master/en-us/MigrateToComposer/MigrationSteps.html

Project specific extensions

Almost all projects use project specific TYPO3 extensions, for example a sitepackage extension.

To provide an extension that is not available via the public composer repository, we need to put the extension and all it's files in the packages subfolder:

{project_name}
└─── packages
   └─── {extension_key}
     |  composer.json
     |  ...

It's mandatory to have a composer.json for each extension. So we create it (if it's not there yet).

./packages/extension_key/composer.json

Make sure to replace the values (like extension_key and ExtensionNamespace) with the correct information. Make especially sure that the required typo3/cms-core version matches the core of your TYPO3 installation.

{
    "name": "extdev/extension_key",
    "type": "typo3-cms-extension",
    "description": "Extension Description",
    "license": "Unlicense",
    "require": {
        "typo3/cms-core": "^10.4.0"
    },
    "extra": {
        "typo3/cms": {
            "extension-key": "extension_key"
        }
    },
    "autoload": {
        "psr-4": {
            "ExtDev\\ExtensionNamespace\\": "Classes"
        }
    }
}

./composer.json

Require the extension by adding it to ./composer.json

{
    "require": {
        // [...]
        "extdev/extension_key": "@dev",
        // [...]
    }
    // [...]
}

 

Initializing the project via composer install

docker-compose up
docker-compose run composer install

 

Run chmod

Composer will generate a bunch of files. Since composer is running out of a docker container all files will be owned by root:root. To change this, run:

sudo chown user:user -R *

 

Update git

git add .
git commit -m '(composer) migration completed'
git push

 

Automatic deployment via GitLab

If you want to configure automatic deployment to staging/live environment via GitLab, have a look at the documentation.

Setting up local development

If you want to start developing locally you need to set the dynamic part of the website up (database, fileadmin etc.). See the documention.

Final file structure

{project_name}
│ .gitignore
│ .gitlab-ci.yml
│ LICENSE
│ composer.json
│ composer.lock
| docker-compose.yml
└─── config
|  └─── sites
|     └─── {project_name}
|       |  config.yaml
└─── docker
|  └─── typo3
|    |  Dockerfile
|  └─── database
|    |  Dockerfile
└─── packages
|  └─── {extension_name}
└─── public
|  └─── typo3conf
|    |  LocalConfiguration.php
|    |  PackageStates.php