Possibly Missing Configuration Instructions in Tutorial Setup Guide

Using Neos & Flow Installation & Deployment
1

Hi

I started using Flow two days ago. I set up a virtual machine containing Ubuntu 18.04, MariaDB, Apache, PHP and Composer and configured as little as possible to make the tutorial project work.

I followed the instructions at https://flowframework.readthedocs.io/en/stable/TheDefinitiveGuide/PartII/Introduction.html to set up the tutorial project.

As it happens, the tutorial didn’t run right off the bat. E.g the AllowOverride Directive for the tutorial directory had to be extended to:

<Directory /usr/local/apache2/htdocs/tutorial/>
 AllowOverride FileInfo Options=MultiViews,Indexes,ExecCGI,Includes
</Directory>

Otherwise, the .htaccess file in the Web/_Resources directory triggers errors because of prohibited use of the options Indexes, ExecCGI or Includes.

Furthermore, the DirectoryIndex directive had to be changed from index.html to index.php. Otherwise, the URI dev.tutorial.local shows an index with a list of the files in Web/ instead of redirecting to index.php.

Last but not least, after kickstarting the example application Acme.Blog, http://dev.tutorial.local/acme.blog showed the message “controller not found” until the global Configuration Configuration/Settings.yaml.example was copied to Configuration/Settings.yaml, probably because it configures the router.

I am not yet accustomed to PHP and its frameworks, so I suspect my points might seem obvious to the usual beginners starting with Flow and wouldn’t be worth mentioning. Otherwise I’d like to help to make the entry barrier a bit lower.

There is also a possibility that the configuration I had to imply is tied to my specific environment. E.g. I compiled Apache and PHP instead of using the Ubuntu repositories to download them.

What do you think?

2

Hey, welcome to the Neos community and Flow!

Thanks a lot for the feedback, this is just soooo valuable for a simple reason: once you went through those common stumbling blocks once or twice, you just don’t see them anymore and hence they’re likely not mentioned in tutorials. Sometimes, things just change after the documentation was written and no one thinks of adjusting docs slightly. But this is so important to make the entry barrier as low as possible, as you say.

I suspect my points might seem obvious to the usual beginners starting with Flow and wouldn’t be worth mentioning.

Not at all! Documentation should optimally be written with basically next to zero assumed previous knowledge.

So you see, that has nothing to do with you, you even did awesome in patiently resolving the issues yourself and then also spending your time to write things down! So thanks again.

E.g. I compiled Apache and PHP instead of using the Ubuntu repositories

This could indeed play a role, albeit a small one. For example, the installation of apache through the repository on Ubuntu will automatically set a DirectoryIndex value containing index.php (See https://help.ubuntu.com/lts/serverguide/httpd.html#default-settings).

until the global Configuration Configuration/Settings.yaml.example was copied to Configuration/Settings.yaml

That definitely should be mentioned in the documentation! That’s one of the things you only fall for once, but which are specific to Flow and can be a stumbling block. I also think this changed at a point when Routing configuration was moved to the Settings. After some quick search, I even found that we even were aware, that adjusting the documentation was necessary, just no one acted upon that (Flow Default Routes never included in basic flow installation · Issue #868 · neos/flow-development-collection · GitHub). So let’s set that straight!

You’re welcome to take a look at that suggested documentation change and say if you find it lacking or maybe even too verbose.

1 Like
3

I wasn’t expecting such a kind welcome - and so soon! Thank you very much!

I might even try the installation tutorial with a more usual setup, like downloading the web server and PHP from the official Ubuntu repository and see if I can go through the tutorial with ease and provide more feedback.

The added explanations in the pull request look fine to me. I will check it in context of the whole tutorial later. At first glance, I thought the reader might miss that there are to different configs: The global one and the one local to a package.

When I tried to make a command controller, an error concerning the fluid template of the command controller was displayed. I found a matching bug report surprisingly fast (Googles accurate search results for a few key words are quite scary at times): https://github.com/neos/flow-development-collection/pull/1644/files. I figured a newly introduced version of the template software might have trouble interpreting the template which is why the “<![CDATA[” tag was introduced in the bug fix to avoid parts of the template from being parsed, but I might be wrong. I checked my flow version (5.3.2) and the tag on the bugfix (neos:5.3) which lead me to think that the bugfix should already have been applied to the version I am using. As this was not the case, I applied the patch myself.

I am eager to learn more about the framework as I will likely use it extensively in my future work environment.

1 Like
4

Glad you feel welcome, that’s our goal :slight_smile:

The commit is indeed in 5.3.3 (and master), as you can see by inspecting the “Commit” view in github - the tags below the commit message will show in which versions this code change is included.

It could be that we still missed some places where the change would be necessary in the kickstarter - guess it just isn’t really used that frequently any more, so we’re a bit lacking in keeping it up to date.

I am eager to learn more about the framework as I will likely use it extensively in my future work environment.

That’s nice to hear! Wish you good luck and don’t hesitate to ask here or on our slack channel if you ever encounter some more stumbling blocks.