fter using Docker for years (and being less and less satisfied with the experience on a Mac), I was looking for alternative and - most importantly - easy and painless to use dev environments. I found Devbox. And I like it!
So, in this tutorial, we're going to install Neos CMS with the Neos.Demo site package using Devbox.
Let's dive in!
Info
While I'm using macOS, you should be able to follow along for other operating systems as well. Devbox can be installed on various systems.
Prerequisites
Install Devbox (You can look it up here for other OS):
For this tutorial, we assume a project directory neos-devbox. You can choose any name, of course.
Init Devbox
Open a terminal window and type:
A devbox.json file is created. It's pretty empty for now, but the packages you add to your Devbox are saved here, as well as the scripts you might add for convenience. It's very similar to the package.json of NPM managed applications.
Checking requirements
As our goal is to setup a environment for our Neos project, let's check the requirements for the framework in the official docs.
We're going to install Neos 9 on PHP 8.3 with MariaDB and Apache. Neos (or rather Flow, the underlying PHP Framework) needs some PHP modules to function, so we'll add them, too. For image processing, we choose ImageMagick. Since Neos and its packages are (thankfully!) Composer managed, Composer is added into the mix as well.
Finding packages
Devbox lets you search for packages with devbox search <package> or devbox search <language>. So if you want to look around, try devbox search php.
Installing packages
Adding required packages is straight forward. Just use devbox add <package> and you're good to go.
For Neos, the command with all the required packages looks like this:
I like to install node.js as well, because I use NPM to handle my frontend stack. A simple devbox add nodejs@22 will do. We're installing a specific version here - when in doubt, I like to go with LTS versions.
Executing the add command installs the packages. You get feedback for every single one, e.g. if and how you can set environment variables. You can always access the info for each package again by running devbox info <package>.
By now, you're devbox.json should look something like this:
Start devbox
Let's start up devbox with devbox shell.
On the first run, it's ensured that every package in your devbox.json is actually installed. The first time, you'll see some info and recommendations (e.g. to install MariaDB securley, and so on), but now, you're logged in your devbox server.
You can check with php -v and you should see an output like this:
Exit devbox
To exit the devbox shell, just type exit in the open terminal session.
To go back in to interact with your application on your server, just run devbox shell in your root directory (in this case neos-devbox) again.
Adding scripts to devbox
Our basic environemt is set up, let's continue with configuring some scripts inside the devbox.json file to help us (and contributors or team members) to install the application.
Open up devbox.json and add the following scripts - you can remove the test scripts added upon installation or keep them, it does not matter.
If you're familiar with NPM and its package.json, those scripts probably are not news to you. You can define a key / name of your command (e.g. composer:create-project) and one (single line) or mulitple (one command in every line) commands to be executed upon calling the script.
So, to run a command, open up a new terminal window. It's important that you execute those scripts in your root directory but not while logged into devbox shell. Like devbox add, running scripts is easy, you just type devbox run <script-name>.
Our two scripts serve the purpose to add a new database for our application and to create the neos project with composer.
Add database
We need to start the services in our dev environment. MariaDB, PHP-FPM, etc. need to run for us to work with. We can start them with devbox services up and stop them with devbox services stop (or hitting CTRL + C in the respective terminal window).
You can also start a specif service with devbox services up mariadb -b (-b launches it in the background without a fancy terminal output).
We're going to start all services now in a new window:
You'll see an output with MariaBD and its logs as well as PHP-FPM running.
In a separate window (again, not in devbox shell), let's run the script to create our database:
The database with the name you chose in the create table statement has been created.
You can check and interact with mysql via terminal in devbox shell, but I like to use a GUI for database handling most of the time. I use Sequel Ace or TablePlus, but you can use whatever you're accustomed to.
The configuration is really easy, it's just entering the host (127.0.0.1) and username (root) and connect to the database. You should see and be able to select the newly created database neos_devbox.
Since this is your local dev environment only, you do not need to configure a separate user and password and can just use root. If you want to or are uncomfortable with it, check out user creation and granting permissions to users and tables in MySQL.
Install Neos
Finally, let's install Neos itself. It's going to require a few steps, but I'll run you through it.
In a new window, run:
You'll see composer doing its job downloading and installing all required packages. But after the output of ./flow welcome and a pretty ASCII illustration of the Neos logo, the installation will abort. This is due to the fact that the php binary can not be localized.
But, fortunately, the output is already telling us the correct path and where to put it.
Essential are the infos "Neos.Flow.core.phpBinaryPathAndFilename" in Configuration/Settings.yaml and the correct php binary path /nix/store/671kccn1vbqiya334605rp5rj1zj6g23-php-with-extensions-8.3.21/bin/php. Your path to nix/store/ of course will be different and you'll have to use your path.
In your IDE, navigate to source/Configuration/Development and add a new file Settings.yaml. Besides the php binary, we'll configure the database connection, image processing and baseUri as well.
After adding this file, we continue with the setup. Answer the prompts for backend user creation.
To check your installtion, run:
All steps should be highlighted green and the descirption be like services running, scripts executed, and so forth.
Start flow server
In devbox shell, run:
Open http://127.0.0.1:8081 in your browser. You installed Neos CMS! 🥳
You can access the backend with http://127.0.0.1:8081/neos and login with the credentials you entered when executing the command ./flow user:create --roles Administrator.
Add Flow server script to devbox
To easily start all our required services when we want to run our application, let's add another script to the devbox.json, e.g. below the db:create script.
So the next time you need to start your Neos site and access it, you'll only need to run:
Next time, we're going to start our own site package without Neos.Demo to get to know Neos internal workings with NodeTypes, Prototypes, Fusion and AFX.
Stay tuned!
