Support Surf or move to an other deployment tools

Hi, currently Surf lack documentation and adoption outside of the TYPO3 / Neos communities. The activity in the Surf channel on the TYPO3 slack is really low and merging something take ages … so what to do with the current situation ?

Technically Surf is pretty good but need more love to be more consistent and well documented. Getting adoption outside of our communities should be hard from my POV.

Surf is just a deployment tools, did we need to maintain our own tool (and did we have the man power) and can we move to something more “standard”


Two thoughts:

If we can achieve (almost) the same with a different tool, let’s go for it and document how you can deploy Flow / Neos with that tool. Deployer looks promising, but I think it’s lacking some features we need. We must consider what it means for all the shops using Surf currently: does it just take a couple of days for us to make Surf fit for the future? Then those agencies should raise some little funds enabling us to improve Surf, because it would be way more expensive (in total) to ask everybody to introduce a completely new tool.

Secondly: the kind of deployment Surf, Deployer, Capistrato et al are implementing goes a bit out of fashion when you start using Docker, Kubernetes etc. But even container orchestration tools don’t solve all the tasks needed for deploying an application like Neos (we still need to run migrations, roll back etc). So, from my point of view, keeping Surf would also allow us to implement new container-friendly features which solve everything we need for deploying Neos.

It’s realistic to raise funding for a Surf 2.0, probably needing 4-6 weeks of development time. Question is if someone would like to 1) raise the funds and 2) would love to work on that.

1 Like

You also need some tool to provision Docker containers, and in that regard Ansible really shines. Doing everything via shell scripts is really a no-go (we currently do that in million12 docker Neos image, and I’d much rather see Ansible there in place of complex shell scripts).

I currently use Surf in production for simple deployments, but don’t object making a switch, so far Surf looks like yet another in-house tool that didn’t get much traction outside.

I don’t want to be harsh … but I don’t see a really bright futur for Surf, yes it’s used currently and the current version will continue to work for existing customers. But we need a clear decision on those point:

  • Is Surf a TYPO3 or Neos project ?
  • If it’s a TYPO3 project does to project want to support the tools on the long run ?
  • If Neos take care of the tools, is it more work to maintain the current code base or to contribute to something else and join effort with an other opensource project (trying to fight our NIH syndrom)

Based on the current activity on git or the slack channel of surf, I’m not sure if Surf is feature complete and don’t need more work … or if no body want to work on it currently.

fully agree with dmitri and dominique, surf isn’t bad, but the question should
really be if there is any sensible scope to keep another chunk of NIH code
running, when there’s plenty out there that provides a solid core and could
easily be extended to serve the purpose.

i toyed around a bit with deployer, not for deployment of flow itself, but i used
it as a build/deployment for beard. quite nice and simple to use as far as i can
see. (

next flow project that’ll come up i’m pretty sure i’ll go for a deployer route
instead of surf. i’ll share that of course when the time comes.

I also think it makes sense to evaluate some existing tools and check how easily they could be used for deploying Flow/Neos and also how hard it might be to move from Surf to that. I agree that there currently is no movement, even though it is a fine tool.

Some quick additionally to what @dfeyer posted:

1 Like

so, i toyed around a bit yesterday and came quite quickly to a working solution (aside from the regular shared hosting issues, argh ^^)

Here’s a basic working deployer deploy script to deploy a flow distribution through checkout&install or rsync to a remote server:


@mneuhaus Thanks for trying deployer, look really nice, and my fav solution currently, but I don’t spend lots of time testing alternative.

From my POV of view, on this topic we need to clearly define the following question first:

Is Surf a TYPO3 or Neos project ?

Currently it’s a TYPO3 project, but regarding git and slack activity around Surf, I have to say it’s more or less dead. If we decide to keep Surf as the default deployment solution for Flow/Neos (and it’s fine, Laravel also has their own tooling with Envoy), we need to get the product under the Neos project umbrella.

If we get it under the Neos project, we need a clear product description on the new website, and work hard on the documentation and polishing.

My opinion: it doesn’t matter, if we would stop using it.

I would choose Deployer as our recommended deployment tool, add a sample deployment script to Flow docs and focus on more important stuff.

However if we do choose to keep it, then indeed we should move it to our umbrella and actively maintain it.

I think the project is dead soon unless we move it under the Neos/Flow project.

Either way we have to provide good documentation on how to setup deployments for Flow and Neos as it’s not easy to do it when your doing it for the first time, no matter if it’s Surf or Deployer.
And there are many caveats with different environments currently.

I’m fine with Surf as I used it for years and it get’s the job done.
But it was always a struggle to adapt it to new environments and debug a failing deployment.

If we decide on Deployer we should make it easy to make all the required helpers and best practices available in a project. Thought of a Flowpack but then we would need to run composer before we can do deployments.
At the same time we could also provide some kind of “interface” which deployment tools would have to implement in their config to basically support Flow/Neos. Then people could post cookbooks on how to do it with Fabric or any other tool.

there’s a way to add custom/additional recipies to deployer globally:

install the custom repositories in the global composer directory:

composer global require deployphp/recipes

add that global composer path to your include_path:

set_include_path(get_include_path() . PATH_SEPARATOR . getenv('HOME') . '/.composer/vendor/');

require anything you need from that package:

require 'deployphp/recipes/recipes/rsync.php';

we can use the same way to create a flowpack/deployer package that can
be installed globally

i used it now for 1 Flow project and another little custom php project and i’m quite pleased so far.


We are migrating away from surf to ansible. Don’t really see a reason why we’d still invest in Surf.

1 Like

@radmiraal well, I don’t that’s a good argument for or against Surf in general. I mean, at Flownative we don’t use Surf either (we are building Docker containers) but that doesn’t mean that the majority of Flow / Neos users does or can do the same.

My 2ct: if we have a well documented way to deploy Neos / Flow with Deployer or some other tool, without major drawbacks in functionality, so be it, then let’s move on and say goodbye to Surf. On the other hand, if it’s a big hassle for ours users and Surf is better for them in the long run, then let’s clean up Surf, make it a Phar file and everybody will be happy (there won’t be much maintenance necessary).

If we need to make it a slim phar file, we need a slimmer Flow :wink:

I think we don’t hurt anybody, Surf will still exist in the current form, it’s a TYPO3 project, they can decide on the EOL or to make some kind of working zombie project. Any way, people will still be able to use it with the current feature base.

Hi there,

I think it’s not valuable to invest into Surf as a standalone project. I will continue to use it for our deployments because it gets the job done. The other question is what we as a Neos project suggest as the preferred way of installing Flow applications (that includes Neos). Because that just doesn’t work as most people expect from a PHP application (unzip, copy/FTP to server, run installer). Ofc you want to have a professional deployment process, but you won’t have a good experience with Neos if you don’t use one (which means learning new concepts for some people).

So regarding the Neos project I’d say to come up with the most simple solution that can be used for beginners and for medium sized professional projects. Whatever the solution will be, it will be our responsibility to document and communicate that because of the not-so-ease-of-use when deploying Flow apps.

In the end it maybe was a bad decision to use Flow as the underlying framework for Surf because it’s really not needed to execute a few tasks. A simple container and CLI option handling would be enough. As you can see with Deployer having a domain model, clean architecture etc. is the opposite of their script-like approach.

As we want to focus on Neos a custom deployment solution will drain energy and focus. And containers might do the job in the future so the landscape has changed in the meantime.


So it seems everyone agrees on the need to officially discontinue Surf and point our users to some other tool? Should we announce it somehow?

I personally fell in love with Ansible. Here’s a simple Ansible script that does for me all Surf did, inspired by @radmiraal’s solution.
Ansible is cool for provisioning Docker containers too. I really hated to provision Docker containers just with shell scripts: no way to use them outside of Docker, hard to test etc.

1 Like


+2 for going the Ansible-way; we used it a lot in the past and are still extremely happy with it!

All the best,

1 Like

No idea of how such an Ansible script could be simplified using custom tasks, but the way it is linked above, it contains way too many technical details. Details that Surf (successfully) hid in favor of coming with a convention for e.g. the file system structure on the target side.

@kdambekalns it’s just a quick-n-dirty hack, that took me half an hour to put together. However I like it that I have all the technical details transparent and in one 100-lines long file.
Normally such script would be split into multiple roles and allow just as much abstraction as Surf did.

i’m currently using Ansistrano which is a Capistrano role for Ansible. It support multiple deployment strategies like rsync, git, scp and shared folders (media, configs etc.). I think it would be a great starting point for a neos/flow role for ansible.