Build composition from template

composition:build-from-template

Description

Build a Docker composition from a template that describes the composition services and their configuration.

Usage

Generate composition files in the current directory:

php "${DOCKERIZER_PROJECTS_ROOT_DIR}bin/dockerizer" composition:build-from-template

You will be asked to choose a template (see How it works) and enter the required parameters in the interactive mode. If current directory contains a composer.json file, then the command will suggest suitable templates for the project. Suitable templates are listed above the list of all available templates if available.

The result is stored to: <current_directory>/.dockerizer/awesome-project.com-prod/. Use --with-environment option to generate and share environment-specific compositions for your project.

In the nearest version, templates will be extracted into the separate repository. You'll be able to add and manager your own templates.

Advanced usage with parameters:

php "${DOCKERIZER_PROJECTS_ROOT_DIR}dockerizer_for_php/bin/dockerizer" composition:build-from-template \
    --template=magento_2.4.6_nginx_varnish_apache \
    --domains='awesome-project.com www.awesome-project.com' \
    --required-services='php_8_2_apache,mariadb_10_6_persistent' \
    --with-environment=prod \
    --with-mysql_database=awesome_project_db \
    --with-mysql_user=awesome_project_user \
    --with-mysql_random_password='q1w2E#R$' \
    -n

Command options

• --path (optional): set the path to the project root directory. Default: getcwd().
• --no-dump (flag): write the result files to the filesystem. Default: true. Is used internally by the magento:setup command. Dry run mode may be added later.
• --domains (required): a list of project domains. For now, it is required even for the CLI compositions. Maybe this will be changed in the future.
• --template (required): a template name. Check available templates here: Check available templates here: composition templates.
• --required-services (optional): a list of required services.
• --optional-services (optional): a list of optional services.
• -f (--force, optional): force the command to stop and delete existing files if any.

You can enter templates, domains, required-services, optional-services in the interactive mode.

The command will select a service automatically if only one option is available. For example, if some Magento version supports only one Elasticsearch version, the command will select it automatically. If there are multiple options, the command will ask you to select one.

How it works

Docker compose service configurations (Apache, Nginx, MySQL, etc.) are stored in /templates/vendor/**/service/ directory, one file per service. These files contain {{parameters}} that are replaced with the actual values.

Composition templates are stored in /templates/vendor/**/composition/ directory. They describe which services can be used together and define the default {{parameter}} values. You can override these values with the command options like --with-parameter=new_value. For example, this way you can change the MySQL version or the web root directory. This is especially useful for automation when there is no need and no way to ask the user for the values interactively or manually edit composition files.

As a result, your composition consists of the following files:

• docker-compose.yaml - the main composition file.
• docker-compose-dev-tools.yaml - composition file with development tools.
• All files mounted to the container. For example, Apache service mounts a virtual host file (see /templates/vendor/defaultvalue/dockerizer-templates/service/php/apache/virtual-host.conf), or Varnish mounts a VCL file.

Every service may be configured for a specific platform. This is why there are, for example:

• magento* templates for Magento 2 and dv_varnish_magento service configured for Magento 2 and mounting its VCL file.
• shopware* templates for Shopware 5/6 and dv_varnish_shopware_6* services configured for Shopware 6 and mounting a different VCL file.

The directory /templates/vendor/**/dev-tools/ contains services that extend or modify the main composition. For example, /templates/vendor/defaultvalue/dockerizer-templates/dev_tools/phpmyadmin.yaml adds phpMyAdmin to your composition. This way, you can configure your own set of development tools which is specific to your compositions and services.

This is a production-like composition: docker-compose -f docker-compose.yaml up -d. It works better for CI/CD, for QA, etc.

Running the same with development tools like xDebug and phpMyAdmin: docker-compose -f docker-compose.yaml -f docker-compose-dev-tools.yaml up -d --force-recreate.

SSL Certificates

Check the below in case of SSL errors and when the certificate CN in the browser says Traefik DEFAULT CERTIFICATE:

1. If the SSL certificate is not valid in Chrome/Firefox when you first run the app URL then run the following command and restart the browser:

mkcert -install

2. If you generate a composition with the same main domain and different set of additional domains then you need to restart Traefik to reload certificates.

Using custom Dockerfiles

You may need to use custom Dockerfiles with additional packages or configurations. You can, for example, change the desired docker-compose*.yaml file and add the build section to the service configuration.

Note that project files are located higher in the directory tree. This is why for containers working with the project files you need to use:

services:
  php:
    build:
      context: ./../../
      dockerfile: ./dockerfiles/php/Dockerfile-production

Remember that adding a custom PHP Dockerfile based on the defaultvalue/php:{{php_version}}-production image to your docker-compose.yaml most likely means that you also need to change the docker-compose-dev-tools.yaml and use Dockerfile-development based on defaultvalue/php:{{php_version}}-development.

Further working with containers

Any operation like running Composer, PHP scripts or Magento commands, etc. MUST be performed only inside the container. In the same way, you must use MySQL client or mysqldump inside the MySQL container.

See an article about Bash aliases that will make your development easier and bring fun to it!

IMPORTANT!

Any application must be installed from inside the running container. At the same time, you need to have, for example, web root and logs directories to configure the composition. This is usually not an issue when you close some existing application from the repository. But what to do when you need to run composer create-project or another command to install your application or framework? Check Install Symfony with Dockerizer to find out how to do this.

See Running-apps-with-existing-Docker-compositions to learn how to run your existing Dockerized applications.

Required environment variables

• DOCKERIZER_PROJECTS_ROOT_DIR: The directory where projects are stored. Acts as a firewall to prevent commands from deleting files outside of this directory or system temp directory.
• DOCKERIZER_SSL_CERTIFICATES_DIR: In the docker-compose.yaml - the directory where SSL certificates are stored.
• DOCKERIZER_TRAEFIK_SSL_CONFIGURATION_FILE (.env.local): The path to the Traefik SSL configuration file. Configured automatically to /home/$USER/misc/apps/traefik-reverse-proxy/traefik/configuration/certificates.toml when you install Traefik (see Configuring the tool section on the Wiki home page).