Well contained: Running TYPO3 in Docker

For the 10th edition of my book Practical Knowledge in TYPO3 (original title Praxiswissen TYPO3) that is going to be released end of this month, I was looking for a way to offer readers an easy quickstart with TYPO3 - for all operating systems. The Windows installers that used to circulate among the TYPO3 community are hopelessly outdated and a from-scratch installation on unixoid operating systems also had its pitfalls.

Since I’ve been working intensively with Docker and seeing as Docker offers an easy installation on all operating systems (thanks to the Docker Toolbox or Docker for Windows and Docker for macOS, respectively), I opted to build my own Docker image for TYPO3.

First steps

The TYPO3 image is available on Docker Hub by the repository name martinhelmich/typo3. You can use the docker pull command below to retrieve the current version of the image:

$ docker pull martinhelmich/typo3

Furthermore, you can use the docker pull command to download a specific version. For this, the repository offers the following tags:

• martinhelmich/typo3:6 for the current 6.2 LTS version (CAUTION no further updates available)
• martinhelmich/typo3:7 for the current 7.6 LTS version (CAUTION no further updates available)
• martinhelmich/typo3:8 for the current 8.7 LTS version (CAUTION no further updates available)
• martinhelmich/typo3:9 for the current 9.5 LTS version
• martinhelmich/typo3:10 or martinhelmich/typo3:latest for the current 10.4 LTS version

Please keep in mind that TYPO3 versions up until version 8 have already reached their designated end-of-life. This means that these versions will not receive any further updates (versions 7 and 8 still do still get updates if you pay for the Extended Long Term Support).

The image only contains a web server with PHP. To follow Docker’s “One container, one service” philosophy, the database management system should best be started in its own container, for example using the mysql image:

$ docker run -d --name typo3-db \
    -e MYSQL_ROOT_PASSWORD=yoursupersecretpassword \
    -e MYSQL_USER=typo3 \
    -e MYSQL_PASSWORD=yourothersupersecretpassword \
    -e MYSQL_DATABASE=typo3 \
  mysql:5.7 \
    --character-set-server=utf8 \
    --collation-server=utf8_unicode_ci

Having a running database, you can start the actual application container:

$ docker run -d --name typo3-web \
    --link typo3-db:db \
    -p 80:80 \
  martinhelmich/typo3:10

After that, your TYPO3 installation can be reached at http://localhost (in case you are using the Docker Toolbox on Windows or macOS, use the IP address of the Docker VM instead. You can determine this IP address by running the docker-machine ip command).

The TYPO3 running in the container is not fully installed, yet. This means that you will need to complete the Setup Wizard, first.

Production deployment

The practice described above is more than sufficient for a demonstration, testing or development. If you want to use the martinhelmich/typo3image in production, there are a few more things that you should keep in mind.

In production usage, it is especially important to worry about any kind of persistent data for your TYPO3 installation. The image already contains pre-configured volumes for the four directories

1. /var/www/html/fileadmin
2. /var/www/html/typo3conf
3. /var/www/html/typo3temp
4. /var/www/html/uploads

These four directories usually store data that should be persistent. The typo3temp/ directory is a special case; the files within it are not particularly important, but TYPO3 will read and write intensively from/to this directory. For performance reasons, it usually is a good idea to create a volume for this directory.

For storing persistent data, you can create a data only container, first. This container will not be running, but is only used to contain the volumes for persistent data (which is why it might be a good idea to override the container’s CMD with /bin/true).

$ docker run --name typo3-data martinhelmich/typo3:10 /bin/true

The actual application container can then be started with the --volumes-from flag:

$ docker run -d \
    --name typo3-web \
    --link typo3-db:db \
    --volumes-from typo3-data \
    -p 80:80 \
  martinhelmich/typo3:10

Using this kind of setup, version updates and deployments will become easy, later. For this, simply delete the typo3-web container. All the important persistent data will remain safely in their volumes managed by the typo3-data container, and a new typo3-web container can be created using the same way as before:

$ docker rm -f typo3-web
$ docker pull martinhelmich/typo3:10
$ docker run --name typo3-web ...

Under the hood

The Dockerfiles used to build the images presented here can be found on GitHub. Suggestions in form of issues and pull requests are always welcome. All images are based on the official php image (more precisely, the php:7.4-apache image) and contain all required PHP extensions required for running TYPO3.