Surf

Package name

typo3/surf

Version

main

Language

en

Author

Neos Team & TYPO3 Team & Contributors

License

This document is published under the Creative Commons BY 4.0 license.

Rendered

Sat, 10 May 2025 23:46:27 +0000

This package is a powerful and flexible automated deployment tool for PHP projects. It is best suited for, but by no means limited to, deploying TYPO3, Flow and Neos applications. It is inspired by some features of Capistrano (thank you) in terms of the Git workflow.

Table of Contents:

Introduction

Surf package is a complete automated deployment tool. It is best used but by far not limited to deploy TYPO3 CMS and Flow applications. It's inspired by some features of Capistrano (thanks) concerning the Git workflow.

Some features of Surf:

• Remote checkout of Git repositories with submodules
• Flexible, declarative configuration of deployments
• Multi-node, multi-application, multi-deployment deployments
• Hook in any deployment stage
• Create custom tasks with a few lines
• Simulate deployments with a dry run
• Easily extendable for other types of applications

Installation

There are several ways to install Surf:

1. Download phar archive
2. Global composer installation
3. Local composer installation
4. Building a Surf phar from source

mkdir /usr/local/surf
curl -L https://github.com/TYPO3/Surf/releases/download/3.6.2/surf.phar -o /usr/local/surf/surf.phar
chmod +x /usr/local/surf/surf.phar
ln -s /usr/local/surf/surf.phar /usr/local/bin/surf

surf self-update

composer global require typo3/surf:^3.6

composer require typo3/surf:^3.6

Usage

After installing Surf you have to create one or more deployment configuration files for your project. The deployment configuration files are at the moment just plain php files. So you can do what ever you can dream of what is possible with php itself. We recommend to keep the deployment configuration as simple as possible and do it in the first place in a procedural like style.

Per default Surf expects the deployment configuration files within the .surf directory in your project.

If you like you can specify the configuration directory with the command option --configurationPath (Rollback deployment) or you could add an environment variable called SURF_WORKSPACE.

But for now we are going to place our deployment configuration files in the .surf directory.

We start by creating a simple deployment configuration in ~/.surf/MyDeployment.php for a deployment with name MyDeployment:

<?php
$node = new \TYPO3\Surf\Domain\Model\Node('example');
$node->setHostname('example.com');
$node->setDeploymentPath('/home/my-flow-app/app');
$node->setOption('username', 'myuser');

$application = new \TYPO3\Surf\Application\Neos\Flow();
$application->setVersion('4.0');
$application->setOption('repositoryUrl', 'git@github.com:myuser/my-flow-app.git');
$application->addNode($node);

$deployment->addApplication($application);

That's a very basic deployment based on the default Flow application template TYPO3\Surf\Application\Neos\Flow. The deployment object is available to the script as the variable $deployment. A node is basically a deployment target representing a server for an application. The node is assigned to the applications for the deployment. Finally the application is added to the deployment. Depending on the usecase, the deployment path can also be set in the application object which is then set for all nodes. This is especially useful if you have several applications which you want to deploy to the same node for example a backend and frontend application.

Each application resembles a repository with code. So a more complex deployment could both deploy a Flow application and release an extension for a TYPO3 CMS website. Also different roles can be expressed using applications, since every task can be registered to run for all or a specific application instance.

In this basic deployment above are a lot of sensitive defaults configured behind the curtains. You are going to explore them in the different chapters of the documentation.

$node->setOption('password', 'yourSshPasswordHere');

$node->setOption('remoteCommandExecutionHandler', function(\TYPO3\Surf\Domain\Service\ShellCommandService $shellCommandService, $command, Node $node, Deployment $deployment, $logOutput = TRUE) {
   // Now, do what you need to do in order to connect to $node and execute $command.
   // You can call $shellCommandService->executeProcess() here.

   // This function should return a two-element array where the first array element
   // is an integer containing the Exit Code, and the second array element is a
   // string with the full, trimmed, output.
});

$ surf describe MyDeployment

$ surf simulate MyDeployment

$ surf deploy MyDeployment

$application->setOption('keepReleases', 2);

$application->setOption('transferMethod', 'git');
$application->setOption('packageMethod', NULL);
$application->setOption('updateMethod', NULL);

Architecture

In order to better understand the concept of the Surf deployment process we will explain some fundamental terminology in this section.

Basically you should grasp the following four main terms to understand the basic concept of the deployment process:

Deployment Flow

If your deployment configuration is not overriding the workflow option, then you are using the default SimpleWorkflow class shipped with Surf.

The SimpleWorkflow class defines 9 stages of the deployment process which are sequentially called. Each stage can consists of none, one or multiple tasks running one after another.

You can add your own tasks for each stage. If you like, you can also specify if your custom task is running before or after a task already defined for this stage.

In the list below you can see all the 9 steps defined by the SimpleWorkflow:

initialize

This is normally used only for an initial deployment to an instance. At this stage you may prefill certain directories for example.

Example Task: \TYPO3\Surf\Task\CreateDirectoriesTask

package

This stage is where you normally package all files and assets, which will be transferred to the next stage.

Example Task: \TYPO3\Surf\Task\Package\GitTask

transfer

Here all tasks are located which serve to transfer the assets from your local computer to the node, where the application runs.

Example Task: \TYPO3\Surf\Task\Transfer\RsyncTask

update

If necessary, the transferred assets can be updated at this stage on the foreign instance.

Example Task: \TYPO3\Surf\Task\TYPO3\CMS\SymlinkDataTask

migrate

Here you can define tasks to do some database updates / migrations. Be careful and do not delete old tables or columns, because the old code, relying on these, is still live.

Example Task: \TYPO3\Surf\Task\TYPO3\CMS\SetUpExtensionsTask

finalize

This stage is meant for tasks, that should be done short before going live, like cache warm ups and so on.

Example Task: \TYPO3\Surf\Task\Neos\Flow\PublishResourcesTask

test

In the test stage you can make tests, to check if everything is fine before switching the releases.

Example Task: \TYPO3\Surf\Task\Test\HttpTestTask

switch

This is the crucial stage. Here the old live instance is switched with the new prepared instance. Normally the new instance is symlinked.

Example Task: \TYPO3\Surf\Task\SymlinkReleaseTask

cleanup

At this stage you would cleanup old releases or remove other unused stuff.

Example Task: \TYPO3\Surf\Task\CleanupReleasesTask

You can create your own workflow if you like. In order to do so you have to extend the abstract Workflow class. The creation of a custom workflow is out of the scope of this chapter. Have a look at the SimpleWorkflow in oder to do so.

// Add tasks to a specific stage
$workflow->addTask('YourTask', 'cleanup');

// Add tasks that shall be executed after the given stage
$workflow->afterStage('YourTask', 'cleanup');

// Add tasks that shall be executed before the given stage
$workflow->beforeStage('YourTask', 'cleanup');

// Add tasks that shall be executed before the given task
$workflow->beforeTask(AnotherTask::class, 'YourTask');

// Add tasks that shall be executed after the given task
$workflow->afterTask(AnotherTask::class, 'YourTask');

// You remove the given task from every application
$workflow->removeTask(FlushCachesTask::class);

// Only remove the task for a specific application
$workflow->removeTask(FlushCachesTask::class, $application);

Applications

The application is the code you want to ship. The deployment configuration has at least one application. But you can configure as many applications as you want in one deployment configuration. The application itself contains of one or more nodes. You can also define within the workflow whether a task is to apply to all applications or only to a specific application.

Surf already ships with specific applications with a sensitive default configuration for the execution process (which tasks are to be called in which stage).

For example there is one application class for TYPO3 or Neos shipped with Surf. But you can create your own specific Application class as long as it inherits from \TYPO3\Surf\Domain\Model\Application.

By default (as long as the application inherits from \\TYPO3\\Surf\\Application\\BaseApplication) an application uses rsync and composer as transfer and package method. But you can also use git, by adding the following configuration to your application:

$application->setOption('transferMethod', 'git');
$application->setOption('packageMethod', NULL);
$application->setOption('updateMethod', NULL);

$application->setOption('gitPostCheckoutCommands', [
   'Packages/Framework/Neos.Flow/' => [
      'git fetch https://github.com/neos/flow-development-collection.git refs/heads/somefix',
      'git cherry-pick FETCH_HEAD'
   ]
]);

Nodes

A node is basically a deployment target representing a server for an application. The node is assigned to an application for the deployment.

A simple node configuration looks like this:

<?php

$node = new \TYPO3\Surf\Domain\Model\Node('example');
$node->setHostname('example.com');
$node->setOption('username', 'myuser');

$application->addNode($node);

<?php

$node->setOption('password', 'yourSshPasswordHere');

<?php

$node->setOption('remoteCommandExecutionHandler', function(ShellCommandService $shellCommandService, $command, Node $node, Deployment $deployment, $logOutput = TRUE) {
   // Now, do what you need to do in order to connect to $node and execute $command.
   // You can call $shellCommandService->executeProcess() here.

   // This function should return a two-element array where the first array element
   // is an integer containing the Exit Code, and the second array element is a
   // string with the full, trimmed, output.
});

Host myhost.uberspace.de
ControlMaster auto
ControlPath /tmp/ssh_mux_%h_%p_%r
ControlPersist 600

Tasks

Since a deployment configuration is just a plain PHP file you can create custom tasks by creating for example a NpmInstallTask class which itself must extend in the whole inheritance chain the abstract class \\TYPO3\\Surf\\Domain\\Model\\Task shipped with Surf:

<?php

namespace Vendor\MyNamespace;

use TYPO3\Surf\Domain\Model\Application;
use TYPO3\Surf\Domain\Model\Deployment;
use TYPO3\Surf\Domain\Model\Node;
use TYPO3\Surf\Task\LocalShellTask

class NpmInstallTask extends LocalShellTask
{
    /**
     * Executes this action
     *
     * @param \TYPO3\Surf\Domain\Model\Node $node
     * @param \TYPO3\Surf\Domain\Model\Application $application
     * @param \TYPO3\Surf\Domain\Model\Deployment $deployment
     * @param array $options
     */
    public function execute(Node $node, Application $application, Deployment $deployment, array $options = [])
    {
        if (!isset($options['command'])) {
            $options['command'] = 'cd {workspacePath} && npm install';
        }

        parent::execute($node, $application, $deployment, $options);
    }
}

In this case we create a task to install the npm dependencies locally. The example shows some simple things to be aware of. First of all you see the string {workspacePath}. This placeholder gets replaced by the full workspace path for the current application.

We will see later that for the remote shell tasks, we have more of these placeholders (Placeholders). Secondly we see that the task defines a default command if none is specified. If you like you can override this option in your deployment configuration. This is valid for all the delivered tasks shipped with Surf.

For this simple task above, we recommend to simplify this by just using the possibility to define your task dynamically by the following mechanism provided by Surf:

<?php

...

$workflow->defineTask('NpmInstallTask', \TYPO3\Surf\Task\LocalShellTask::class, [
    'command' => [
        'cd {workspacePath} && npm install',
    ]
]);

This way you create a task dynamically by extending the base task \TYPO3\Surf\Task\LocalShellTask::class with an array of options. In this case the command option is mandatory for the LocalShellTask.

We will show you another convenient and often used way to customize the deployment workflow with your own tasks:

<?php

...

$workflow->defineTask('CopyEnvFileTask', \TYPO3\Surf\Task\ShellTask::class, [
    'command' => [
        'cp {sharedPath}/.env {releasePath}/.env',
        'cd {releasePath}',
    ]
]);

In this case we create a task dynamically based on the ShellTask. The ShellTask execute one or more provided commands on the target machine. As you can see, we have used some other placeholders compared to the LocalShellTask above. For the remote ShellTask the following placeholders are available:

<?php
/** @var \TYPO3\Surf\Domain\Model\Deployment $deployment */

$application = new \TYPO3\Surf\Application\TYPO3\CMS();
$deployment->addApplication($application);
$workflow = $deployment->getWorkflow();

$workflow->defineTask('CopyEnvFileTask', \TYPO3\Surf\Task\ShellTask::class, [
    'command' => [
        'cp {sharedPath}/.env {releasePath}/.env',
        'cd {releasePath}',
    ]
]);

$deployment->onInitialize(function() use ($workflow, $application) {
    $workflow->afterStage('transfer', 'CopyEnvFileTask', $application);
});

<?php

$workflow->beforeTask(SomeTask::class,
    [
        'CopyEnvFileTask'
    ]
);

<?php

use TYPO3\Surf\Task\Transfer\RsyncTask;

// Customize the option for the task only for a specific application
$application->setOption(RsyncTask::class . '[rsyncExcludes]', [
    '.git',
    'public/fileadmin',
]);

// Customize the option for the task only for a specific node
$node->setOption(RsyncTask::class . '[rsyncExcludes]', [
    'public/fileadmin',
]);

// Customize the option for the whole deployment
$deployment->setOption(RsyncTask::class . '[rsyncExcludes]', [
    '.git',
]);

CLI Usage

After installation of Surf you will have the ability to run the surf command from your terminal.

Surf will by default check for your deployment configurations in the subfolder .surf.

To get list of all available tasks run the surf command:

TYPO3 Surf [version]

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  deploy    Deploys the given name
  describe  Describes the flow for the given name
  help      Displays help for a command
  list      Lists commands
  migrate   Migrates old deployment definitions to new Surf version
  rollback  Rollback current to previous release and remove current folder
  show      Shows all the deployments depending on the directory configuration
  simulate  Simulates the deployment for the given name

$ surf show

$ surf describe MyDeployment

$ surf simulate MyDeployment

$ surf deploy MyDeployment

$ surf rollback MyDeployment

$ surf show --configurationPath myConfigurationPath

Smoke Testing

As you do automated deployments, you should check if the website is up and running before switching it to the live site. This is called a Smoke Test. We will give an example for using the built-in HTTP smoke test.

First, you need to create a virtual host with document root in "<deploymentDirectory>/releases/next/Web". While a deployment is running, the new website will be available under this URL and can be used for testing.

Then, add a test as follows to the deployment configuration:

<?php

$workflow = new \TYPO3\Surf\Domain\Model\SimpleWorkflow();

$smokeTestOptions = [
	'url' => 'http://your-website.com',
	'remote' => true,
	'expectedStatus' => 200,
	'expectedRegexp' => '/somethingYouExpectOnThePage/'
];
$workflow->defineTask('MyCompany\\MyPackage\\SmokeTest', \TYPO3\Surf\Task\Test\HttpTestTask::class, $smokeTestOptions);

$workflow->addTask('MyCompany\\MyPackage\\SmokeTest', 'test', $application);

The HTTP test has the following options:

Most important options:

• url (required): URL which should be loaded
• remote: if TRUE, the smoke test is triggered through the SSH channel on the remote host via command-line CURL. If false, it is triggered from the deploying host.
• expectedStatus: expected HTTP status code
• expectedHeaders: HTTP Header Strings which are expected (can be a multiline string, each header being on a separate line)
• expectedRegexp: Regular Expression to test the contents of the HTTP response against

Further options:

• timeout (only if remote=FALSE): HTTP timeout to use
• port (only if remote=FALSE): HTTP Port to use
• method (only if remote=FALSE): HTTP method to use (default GET)
• username (only if remote=FALSE): HTTP Authentication username
• password (only if remote=FALSE): HTTP Authentication Password
• data (only if remote=FALSE): HTTP payload
• proxy (only if remote=FALSE): HTTP Proxy to use
• proxyPort (only if remote=FALSE): HTTP Proxy port to use
• additionalCurlParameters (only if remote=TRUE): list of parameters which is directly passed to CURL. Especially useful to e.g. disable SSL certificate check (with --insecure)

if ($context->isTesting()){
	foreach ($GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations'] as $cacheName => $cacheConfiguration) {
		$GLOBALS['TYPO3_CONF_VARS']['SYS']['caching']['cacheConfigurations'][$cacheName]['backend'] = \TYPO3\CMS\Core\Cache\Backend\NullBackend::class;
	}
}

# Add Rewrite rule near https://github.com/TYPO3/typo3/blob/main/typo3/sysext/install/Resources/Private/FolderStructureTemplateFiles/root-htaccess#L270
RewriteCond %{HTTP_HOST} ^next\.example\.com$
RewriteRule .? - [E=TYPO3_CONTEXT:Testing]

{
	"autoload": {
		"files": ["scripts/typo3context.php"]
	}
}

<?php
// Set the application context in this file because it is not possible to set environment variables
// via .htaccess e.g. on domainFACTORY/jweiland.net servers
$context = 'Production';

// detect application context by domain
if (array_key_exists('HTTP_HOST', $_SERVER)) {
	if (0 === strpos($_SERVER['HTTP_HOST'], 'next.')) {
		$context = 'Testing';
	}
}
putenv('TYPO3_CONTEXT=' . $context);

Deployment Recipes

How to deploy TYPO3 websites

If you would like to deploy a TYPO3 website a good starting point is to use TYPO3CMS Application class provided by Surf:

<?php
/** @var \TYPO3\Surf\Domain\Model\Deployment $deployment */

$node = new \TYPO3\Surf\Domain\Model\Node('my.node.com');
$node
    ->setHostname($node->getName())
    ->setDeploymentPath('/httpdocs')
    ->setOption('username', 'myuser')
    ->setOption('phpBinaryPathAndFilename', '/usr/local/bin/php_cli');

$application = new \TYPO3\Surf\Application\TYPO3\CMS();
$application
    ->setOption('baseUrl', 'https://my.node.com/')
    ->setOption('webDirectory', 'public')
    ->setOption('symlinkDataFolders', ['fileadmin'])
    ->setOption('repositoryUrl', 'file://' . dirname(__DIR__))
    ->setOption('keepReleases', 3)
    ->setOption('composerCommandPath', 'composer')
    ->setOption('rsyncExcludes', [
        '.ddev',
        '.git',
        $application->getOption('webDirectory') . '/fileadmin',
        'packages/**.sass'
    ])
    ->addSymlink($application->getOption('webDirectory') . '/typo3conf/LocalConfiguration.php', '../../../../shared/Configuration/LocalConfiguration.php')
    ->addNode($node);

$deployment
    ->addApplication($application)
    ->onInitialize(
        function () use ($deployment, $application) {
            $deployment->getWorkflow()
                ->beforeTask(\TYPO3\Surf\Task\TYPO3\CMS\SetUpExtensionsTask::class, \TYPO3\Surf\Task\TYPO3\CMS\CompareDatabaseTask::class, $application)
                ->beforeStage('transfer', \TYPO3\Surf\Task\Php\WebOpcacheResetCreateScriptTask::class, $application)
                ->afterStage('switch', \TYPO3\Surf\Task\Php\WebOpcacheResetExecuteTask::class, $application);
        }
    );

How to deploy Neos websites

If you would like to deploy a Neos website a good starting point is to use the Neos Application class provided by Surf:

<?php
/** @var \TYPO3\Surf\Domain\Model\Deployment $deployment */

$node = new \TYPO3\Surf\Domain\Model\Node('production');
$node
   ->setHostname('my.node.com')
   ->setDeploymentPath('/var/www/html/my.node.com')
   ->setOption('username', 'myuser');

$application = new \TYPO3\Surf\Application\Neos\Neos('My Node');
$application
   ->setOption('keepReleases', 3)
   ->setOption('composerCommandPath', 'composer')
   ->setOption('repositoryUrl', '<my repository url>')
   ->setOption('branch', 'main')
   ->setOption('updateMethod', null)
   ->setOption('baseUrl', 'https://my.node.com')
   ->setOption('flushCacheList', [
       'Neos_Fusion_Content',
       'Neos_Neos_Fusion'
   ])
   ->addNode($node);

$deployment
   ->addApplication($application)
   ->onInitialize(
      function () use ($deployment, $application) {
            $deployment->getWorkflow()
               ->beforeStage('transfer', \TYPO3\Surf\Task\Php\WebOpcacheResetCreateScriptTask::class)
               ->afterStage('switch', \TYPO3\Surf\Task\Php\WebOpcacheResetExecuteTask::class)
               ->afterStage('switch', \TYPO3\Surf\Task\Neos\Flow\FlushCacheListTask::class);
      }
   );

How to deploy Flow Apps

<?php
/** @var \TYPO3\Surf\Domain\Model\Deployment $deployment */

$application = new \TYPO3\Surf\Application\Neos\Flow();
$application->setVersion('4.0');

How to deploy Laravel applications

If you would like to deploy a Laravel application a good starting point is to use Laravel Application class provided by Surf:

<?php
/** @var \TYPO3\Surf\Domain\Model\Deployment $deployment */

$node = new \TYPO3\Surf\Domain\Model\Node('my.node.com');
$node
    ->setHostname($node->getName())
    ->setOption('username', 'myuser')
    ->setOption('phpBinaryPathAndFilename', '/usr/bin/php8.0');

$application = new \TYPO3\Surf\Application\Laravel();
$application
    ->setDeploymentPath('/var/www/html')
    ->setOption('baseUrl', 'https://my.node.com/')
    ->setOption('repositoryUrl', 'file://' . dirname(__DIR__))
    ->setOption('keepReleases', 3)
    ->setOption('composerCommandPath', 'composer')
    ->addNode($node);

$deployment
    ->addApplication($application)
    ->onInitialize(
        function () use ($deployment, $application) {
            $deployment->getWorkflow()
                ->beforeStage('transfer', \TYPO3\Surf\Task\Php\WebOpcacheResetCreateScriptTask::class, $application)
                ->afterStage('switch', \TYPO3\Surf\Task\Php\WebOpcacheResetExecuteTask::class, $application);
        }
    );

How to deploy other apps and websites

There are several ways to deploy other projects with TYPO3 Surf. For example, you can:

• Provide a composer package with the application and tasks you need. Particularly useful for complex workflows.
• Use \TYPO3\Surf\Application\BaseApplication or \TYPO3\Surf\Domain\Model\Application in your recipe and enrich the workflow with necessary tasks.

Migration from 0.9.x to 2.0

1. Move deployment scripts form Build/Surf to ~/.surf/deployments
2. Rename task or use migrate command to switch to new task names
3. Set transferMethod and packageMethod options in your application, as the default changed from git to rsync
4. Change options for CreateDirectoriesTask: Now the specified directories are based on the application's release path not the general deployment path (which did not make much sense)
5. Neos CMS only: Add the task TYPO3\Surf\Task\Neos\Neos\ImportSiteTask to the step migrate again if you use the Neos Application and need it to import your content after each deployment

Sitemap

Index