PunktDe Kontakt LogoKontakt
Just type and press enter to search

Neos Tutorial Part 1 - Setting up a development environment easily

Neos Tutorial Part 1 - Setting up a development environment easily

Originally developed by the TYPO3 community, the Open Source CMS Neos is now being further developed by an independent and growing community. Written from scratch, Neos is based on innovative concepts and uses state-of-the-art technology - a big advantage over existing CMS solutions on the market.

These modern approaches have an effect on all kinds of work with a CMS. Editors can edit the content directly on the website. Due to the lack of abstraction of a backend module, the editor has direct control over how the content will look and behave while editing it.

The powerful content repository Neos uses to manage the content internally gives the integrator the ability to tailor content types to the customer's needs and semantically define them. Due to the endless possibilities that result from the definition language for content types with YAML, logic description by Eel and Flowquery and the Template Engine Fluid, third-party extensions or self-development in PHP is rarely needed.

If proprietary development in PHP is actually needed for complex requirements, the developer finds a modern, tidy and modular codebase.
Underlying Neos, the application framework Flow supports the programmer with modern paradigms such as domain driven design and aspect-oriented programming in the development of high-performance applications.

Admittedly, access for newcomers to Neos could be much improved. This is exactly what I aim to achieve with this multi-part tutorial. We start with this article by setting up a local development environment, installing the CMS, and describing the basic structure of the CMS interface. In the following articles, we will work on creating our own website with its own custom content types.

The development environment for this Neos tutorial

Before we can start with the actual installation of Neos, we first need an environment the provides all prerequisites for the CMS. Such a development environment, mainly consisting of web and database servers, as well as other tools and configurations, is a complex system that is difficult to set up on the operating system of your computer. In bypassing this complexity, we want to work with a virtual system. To do this, we use the virtualization software VirtualBox together with the administration tool Vagrant.

Icons of Vagrant and Virtual Box

Develop Neos with VirtualBox & Vagrant.

Using a virtualization software provides several advantages. The files of our host system are not changed - so we can play around without running the risk of harming other applications on our operating system. The virtual environment we use can be generated reproducibly and can be started from zero at any time in the event of a faulty configuration. This also means, we work in an environment that corresponds exactly to what we later find on the production server.

Neos environment with Vagrant and VirtualBox

First, we download the latest version of VirtualBox and Vagrant matching our operating system and run the installation programs of VirtualBox and Vagrant.

After the virtualization tools are successfully installed, the prerequisites for downloading and starting the Neos Box are given. The Neos Box, which we will use as part of this tutorial, is based on the software, which we also use in our hosting and is particularly suitable for working with modern PHP based content management systems. Based on the open source operating system FreeBSD, the box contains the latest versions of the necessary server software. All technical details of the box can be found on this page.

To download the Neos Box, we open a shell and create a new folder in our home directory which we call vagrant-neosbox:

mkdir ~/vagrant-neosbox
cd ~/vagrant-neosbox

Develop Neos on Windows?

In this article, we can only describe how the Neos Box is installed on Linux and MacOS X, because these are the operating systems we use every day and with which we are familiar. But also Windows can be used as a host platform for our Vagrant Box. A detailed description of this operating system can be found here.

Within the folder, we execute the following command:

curl -O https://github.com/punktDe/proserver-neos-box/blob/master/Vagrantfile && vagrant up

The command first downloads the VagrantFile, which contains all setting for our box. Using the command vagrant up, the VirtualBox image is then downloaded from our server and finally started. This can take some minutes.

Once started, we use SSH to open a shell on the box.

The command:

vagrant ssh

executed in the same directory, in which the VagrantFile lies, takes over the login for us.

Congratulations! The perfect environment for our work with Neos is up and running.

Up. Halt. Reload.

Using the vagrant command, the box can be started (vagrant up), stopped (vagrant halt) and restarted (vagrant reload) anytime.

Wit the Vagrant Manager, there is also a tool for MacOS which makes the administration of the box even more convenient.

Let's install Neos

Now we can download the Neos packages. In the box, we navigate to the prepared web server directory and delete the existing test page. We use git to clone the neos base distribution in the current stable version.
The package manager then takes care of downloading the necessary PHP sources. This process also needs a moment to complete.

cd /var/www
rm -rf Web
composer create-project neos/neos-base-distribution .

Once the download of the PHP packages has been completed, we can now access the setup page of our box under with any browser and perform the individual steps of the installation.

First, we need to authenticate with the setup password, which we can access by using the following command:

cat /var/www/Data/SetupPassword.txt

The page, which appears after the successful login, shows us an overview of the installed graphics libraries. Click Next to switch to database configuration. Here we enter "neos" as the user and password and select the database of the same name.

On the next page, we create our initial administration user.

The installation process starts with entering the setup password.

The installation process starts with entering the setup password.

Step 1: Gather facts about the installed graphic libraries.

Step 1: Gather facts about the installed graphic libraries.

Step 2: Enter database credentials

Step 2: Enter database credentials

Step 3: Create the first Neos administrator.

Step 3: Create the first Neos administrator.

In the next step, we have the option to either install the Demo-Site-package included in the base distribution or create our own package.

A site package contains all the files that make up the layout and basic features of a page, such as HTML, CSS, Fusion and graphics.

To start easy for this time, we import the preselected demo package and finish the installation process by clicking on "Next".

Step 4: Import the site package or create a new one.

Step 4: Import the site package or create a new one.

This completes the installation. Clicking on "Go to the Backend" will bring us to the login screen of the backend, where we can log in with the user created during the setup. Later we can access the backend at any time, if we attach a /neos to the URL of the page.

The Neos Backend

The functions of the backend are briefly explained below. Some of the modules will be described in the following detail in later articles.

The Neos backend with navigation bars on the left and the inspector on the right.

The Neos backend. Here you find the Page tree and the content element tree on the left and the inspector on the right side.

Logged in to the backend, the page appears framed by the editing elements of the backend. Let's start with the left sidebar, which is used to navigate and structure the content. The upper part is dedicated to the pages. Using the toolbar above the page tree, new pages can be created and existing pages can be copied, hidden or deleted. Below are search and filter elements, which directly restrict the entries in the page tree. Of course, an existing menu in the page itself can also be used to navigate to other pages.

In the lower part of the page panel, you can expand the structure tree, which displays all content elements of the page in a hierarchy. Although all operations, which can be seen here, can also be executed directly in the content, the work in the structure tree can be clearer, depending on the use case. For example, it is easier to rearrange the content here.

The center of the screen - in the editor's focus - the content of the page is displayed. When clicking on the content, a text for example, it can be edited inline. If an element is selected, control elements appear at the upper end of it which directly affects the selected content.

In the panel above the content, we find a selection menu, which allows us to edit different dimensions of the content. In the case of this demo package, it is possible to edit content in other languages.

The so-called inspector is located in the right sidebar. It shows the properties of the selected page or content, which can not be edited directly inline. These include properties such as the type of the content element, the start and end dates for the time constraint, and also meta information, such as the title and the alt tag of an image.

The module displays a list of available workspaces. This list contains the personal workspace of the currently logged-in user as well as all shared workspaces. New shared workspaces can be created. The "Review" button allows you to view and release changes to a workspace.

The management of all media used in Neos can be done via the media module. Media can be uploaded by selection or drag & drop and categorized with tags to keep track of the assets. A search as well as filter and sorting options help to find the desired medium even with larger asset stocks easily.


The modules under the Administration section will be rarely visited when working with Neos. Therefore, I keep the description short.

  • The user management module allows new users with different rights in the system to be created.
  • The package management shows a list of the existing packages, divided into different categories. It shows whether they are currently activated or not.
  • In page management, pages can be created from existing site packages and domains can be assigned.
  • The configuration module shows the various available configuration options of Flow and Neos. Although it is not yet possible to edit the settings here, the module analyzes the existing settings and reports errors - which makes the module a good start in the search for causes of errors.

For comments and questions about the content of this articles, please use the comment function at the end of the page.

You want to continue immediately? This is the second part of the workshop where we start building our own page with Neos.
I wish you a great fun on trying out Neos!



Other Posts

A toolbar for page properties in TYPO3
19. Januar 2021

A toolbar for page properties in TYPO3

How "Quickedit" could make working with pages easier for editors more

Responsive Images in TYPO3 v10
29. Mai 2020

Responsive Images in TYPO3 v10

In this article I would like to talk about the integration of Responsive Images in TYPO3 v10. Most of … more