Deployments for TYPO3
When running a deployment the following stages and corresponding tasks are executed.
This is normally used only for an initial deployment to an instance. At this stage you may prefill certain directories for example.
- TYPO3\Surf\Task\DumpDatabaseTask (wenn initialDeployment == true)
- TYPO3\Surf\Task\RsyncFoldersTask (wenn initialDeployment == true)
- TYPO3\Surf\Task\UnlockDeploymentTask (wenn --force-run)
This stage is where you normally package all files and assets, which will be transferred to the next stage.
- Madj2k\Surf\Task\Local\Composer\InstallStagingTask OR Madj2k\Surf\Task\Local\Composer\InstallProductionTask
Here all tasks are located which serve to transfer the assets from your local computer to the node, where the application runs.
Update the application assets on the node
Migrate (Doctrine, custom)
Prepare final release (e.g. warmup)
- Madj2k\Surf\Task\Remote\File\CopyDummyFilesTask (only if NOT on production!)
Do symlink to current release. This is the crucial stage. Here the old live instance is switched with the new prepared instance. Normally the new instance is symlinked.
Delete temporary files or previous releases
If you want to deploy your TYPO3 project with this extension, you should create a few folder structures and files to be able to use the full potential.
Contains the configuration for the TYPO3 extension Surf for deployment and the corresponding Deployment-Scripts.
<?php use Madj2k\Surf\Deployment; /** * Deployment-Script * * @author Steffen Kroggel <email@example.com> * @copyright Madj2k * @license http://www.gnu.org/licenses/gpl.html GNU General Public License, version 3 or later * @var \TYPO3\Surf\Domain\Model\Deployment $deployment */ // load options $options = require_once __DIR__ . '/Credentials/Production.php'; // make deployment $myDeployment = new Deployment($deployment, $options);
<?php use Madj2k\Surf\Deployment; /** * Deployment-Script * * @author Steffen Kroggel <firstname.lastname@example.org> * @copyright Madj2k * @license http://www.gnu.org/licenses/gpl.html GNU General Public License, version 3 or later * @var \TYPO3\Surf\Domain\Model\Deployment $deployment */ // load options $options = require_once __DIR__ . '/Credentials/Staging.php'; // make deployment $myDeployment = new Deployment($deployment, $options);
Contains the access data for the respective environments. IMPORTANT: Do not put these files into your versioning!
<?php /** * Credentials * * @author Steffen Kroggel <email@example.com> * @copyright Madj2k * @license http://www.gnu.org/licenses/gpl.html GNU General Public License, version 3 or later * @version 1.0.3 */ return [ 'context' => 'Production/Staging', 'projectName' => 'Example', 'deploymentPath' => '/var/www/example.com/surf', 'phpBinaryPathAndFilename' => '/usr/bin/php7.4', 'adminMail' => 'firstname.lastname@example.org', 'hostname' => '', 'username' => '', 'password' => '', 'port' => '', 'repositoryUrl' => 'https://github.com/Example/Example.git', 'branch' => 'staging', 'doUpgrade' => false, 'queryFileBeforeUpgrade' => '', 'queryFileAfterUpgrade' => '' ];
File: _.htaccess.dev / _.htaccess.prod / _.htaccess.stage / _.nginx.dev / _.nginx.prod / _.nginx.stage
Contains the settings for the given environment. You can use .htaccess for Apache or .nginx for Nginx. Will be deployed automatically.
Same as _htaccess.*
Contains the packages to install.
To be able to install packages that themselves have dependencies on packages that are only available as @dev, you need to specify the
minimum-stabilty in combination with
preferred-install you can specify that certain packages should be installed as GIT repositories so that you can work on them directly.
Contains dummy files for sys_file-references. The content of this folder will be deployed on your stage-environment (of course not on production!)
This file contains a list of all extensions to be activated in the given enviroment.
If this file is copied to
.env before installation, the package "helhum/dotenv-connector" will automatically create a corresponding
# Context TYPO3_CONTEXT="Production" # A set of TYPO3 framework extensions (delivered within typo3/cms), which should be marked as active TYPO3_ACTIVE_FRAMEWORK_EXTENSIONS="about,backend,belog,beuser,context_help,core,cshmanual,extbase,extensionmanager,felogin,filelist,filemetadata,fluid,fluid_styled_content,frontend,func,impexp,info,info_pagetsconfig,install,lang,lowlevel,recordlist,recycler,reports,rsaauth,rte_ckeditor,saltedpasswords,scheduler,setup,sv,sys_action,sys_note,taskcenter,tstemplate,version,viewpage,wizard_crpages,wizard_sortpages"
File: web/typo3conf/AdditionalConfiguration.dev.php / AdditionalConfiguration.prod.php / AdditionalConfiguration.stage.php
This file contains the relevant settings for the according environment.
IMPORTANT: Do NOT put any access data or enycryption keys into versioning that are relevant for the live environment. These are ONLY to be put into
AdditionConfiguation.php on production and stage respectively!!!
For the deployment you need a branch with the same name as the deployment-step you want to execute.
- If you want to deploy into the staging-enviroment you have to push everything to the
- If you want to deploy into the production-enviroment you have to push everything to the
You also need a deployment script with the same name as the branch you want to deploy, e.g
Beyond that it is necessary to create a corresponding credential file in .
surf/Credentials. Use the example above as template.
In case there are any uncommitted changes, please commit them in the corresponding repository to prevent losing them when calling composer throughout the deployment process.
In case you may need a new extension, please don't forget to publish it on packagist. Otherwise it won't be available to standard composer update process.
- In order to make your changes effective, the
composer.lockhas to get the new version information. So in your website-repository do a
vm$ composer update
- The new
composer.lockhas to be committed as well. So you need to push the changes of your website-repository before executing a deployment.
Do the deployment using the following command from your DocumentRoot.
IMPORTANT: The surf extension requires PHP 7 on the CLI
IMPORTANT: Do NOT run deployment with
root or super-user !!! Always use your local user (e.g.
IMPORTANT: Please login to the TYPO3 backend of your target installation (Staging, Production, ...), so you may have access to it, even if anything may fail or break during the deployment with .surf.
vm$ php ./vendor/typo3/surf/surf deploy <DEPLOYMENT-FILE> vm$ php ./vendor/typo3/surf/surf deploy Staging
You can use verbose-output to get more information if something goes wrong:
vm$ php ./vendor/typo3/surf/surf deploy Staging -v vm$ php ./vendor/typo3/surf/surf deploy Staging -vv vm$ php ./vendor/typo3/surf/surf deploy Staging -vvv
- Make sure PHP APCU is installed
apt-get install php7.4-apc php7.4-apcu
- Before running the deployment with
doUpgrade = truemake sure your MySQL-user has the right privileges to execute a mysldump:
GRANT RELOAD, PROCESS ON *.* TO 'my-user'@'%'; FLUSH PRIVILEGES;
- If you have an external server to access, you need to at least install mysql-client
- If you are trying to access an older MySQL-version via MySQL-Client v8+, you should add this line