tl;dr: To easily configure your proServer with Ansible, clone the template repository, copy the appropriate file from `host_vars_examples` to `host_vars`, and customize it and the inventory file for your proServer. Then start the provisioning process with `ansible-playbook`. The playbook writes all configuration parameters to a .env file, which you can then use in your Neos project.
Hosting for Neos CMS Projects
With the modern Neos CMS, even sophisticated and complex web projects can be implemented.
However, Neos itself is no less demanding when it comes to the right hosting environment. These are simple requirements, such as the same modern PHP version for CLI and PHP-FPM, or the appropriate version of MariaDB as the database Backend. Anyone who wants to take full advantage of Neos’ features in larger projects will also need server services that aren’t part of a standard hosting provider’s portfolio: Redis as a fast cache Backend, Elasticsearch for managing and searching large amounts of content, or Supervisor to orchestrate background processes, to name a few.
With the punkt.de proServer, we offer a hosting environment that is optimally tailored to the requirements of Neos and is continuously adapted to meet future needs.
"Infrastructure as Code" with Ansible
Ansible is an automation tool for orchestrating and configuring servers. From a control node, Ansible connects to the target servers via SSH and executes the commands necessary for configuration. No additional software is required on the target server. The Ansible configuration consists mainly of easy-to-read files in YAML format, which are used to define the tasks to be executed.
The advantages of configuring servers with Ansible code over manual configuration are obvious. All configuration steps are traceable and can be reused at any time to configure new server instances identically. Of course, the Ansible code can be versioned just like the project code, ensuring that the infrastructure always aligns precisely with the project.
What is proServer?
With proServer, we’ve created a hosting solution that offers everything a demanding web project needs. Designed by our developers and tested in our project work, proServer is intended to never get in the way of your daily work. It comes with an optimized default configuration that can be fully customized to your specific needs. At the same time, the installed software is updated regularly and automatically.
Technically, the proServer is based on FreeBSD and the Jails container solution. Each jail provides the environment for an entire project or just individual services. With our agency solution, proServer instances can be created at the click of a button.
Our Ansible roles for the punkt.de proServer
And, of course, it makes sense to structure and modularize the Ansible code so that it can be reused for new projects. That’s exactly what we’ve done—we’ve published the Ansible roles we use to configure our instances as open-source projects on GitHub. Our goal is to make it even easier for our proServer customers to get their Neos projects up and running with minimal effort.
Each role encapsulates a specific function—or server service—that needs to be configured. In addition to standard services like NGINX, php-fpm, or databases, you’ll also find configurations that have proven very useful in our day-to-day project work—such as displaying the configured domains during login or an OAuth2 proxy to protect staging instances.
Configuring a proServer with Ansible
To provision a proServer using Ansible, the following four steps are required.
1. Install Ansible
First, Ansible must be installed on the local system. The Ansible Installation Guide provides various options for Unix-like systems. On Windows, Ansible can run in the Windows 10 Subsystem for Linux.
2. Cloning GitHub Projects and Submodules
The GitHub project " proServer-Ansible-Template " contains the generic roles and configuration for this specific project. Use the following command to clone the project and the roles it uses:
git clone --recurse-submodules https://github.com/punktDe/proserver-ansible-template.git
3. Customize the Ansible configuration for your project
Next, you need to specify which proServer should be configured with which roles and services. To do this, you need to modify files in two locations.
host_vars
In the host_vars folder, we need a file for each host in our inventory that describes that host’s specific parameters.
The ` host_vars_examples ` directory contains examples of such a file. For a production proServer on which a Neos instance is to be deployed, we simply copy the file `host_vars_examples/neos/production.yaml ` to `host_vars/production.yaml`.
In the newly created file, you must first replace all instances of “0000” with your own proServer number. After that, you can customize the configurations for the various services according to your preferences.
inventory.ini
The Ansible inventory, which is defined in inventory.ini, contains a list of hosts (per server) and the groups to which these hosts should be assigned. Ansible will later use these groups to assign the necessary roles.
First, comment out one of the host definitions and replace the vpro number. Then, assign the server to the correct group. For a production Neos instance, for example, comment out the “production” line under the “Neos” key.
host_vars Templates
We have created sample templates for the host_vars files in two versions: one for Neos and one for TYPO3. Templates for additional services will follow.
The production.yaml file contains the parameters for the stack consisting of NGINX with a Let’s Encrypt SSL certificate, PHP, and either MariaDB or MySQL as the database Backend. It also specifies the configuration for email delivery and the cluster name for the optional use of Elasticsearch.
The staging.yaml also includes two useful services for staging environments.
The OAuth2 proxy protects the site—which is not yet in production—from unauthorized access. We have preconfigured GitLab as the Backend for authentication, so you can conveniently authenticate via GitLab. Of course, other Backends can also be used; examples can be found here.
Mailhog is the second service, configured exclusively for staging. Mailhog automatically intercepts all emails sent from the CMS, which can then be viewed in a web interface. An API provides access to the mailbox—ideal, for example, for automated frontend testing with Codeception.
4. Start Ansible
Ansible is now configured for its first run and is ready to be started. For example, the following command provisions all servers in the production environment.
ansible-playbook --ssh-extra-args=-oProxyJump=jumping@ssh-jumphost.karlsruhe.punkt.de --limit=production playbook.yaml
The server is now fully configured for a Neos instance. The Neos project is expected to be located in the path /var/www/neos/current —a path that matches a project transferred using Deployer. A sample configuration for deploying Neos with Deployer is already included in our template project.
Bonus: Automatically configure Neos with .env
The Neos Ansible role doesn't just configure NGINX for Neos. It also writes all important configuration variables—such as the credentials for the database or Elasticsearch—to a .env file located at /usr/local/etc/neos.env. Neos can read these parameters using the .env connector.
This has several advantages. Passwords no longer need to be checked into the Git repository. It also eliminates the need to distinguish between staging and production environments in the configurations. If services such as database servers or Elasticsearch are distributed across different hosts, the configuration adjusts automatically without requiring any changes to the project code.
Use the following commands to install and configure the dotenv connector via Composer:
composer require helhum/dotenv-connector
composer config extra.helhum/dotenv-connector.env-file /usr/local/etc/neos.env
The configuration shown here ensures that the parameters are read from the environment.
Our template project already includes the necessary roles and examples for the automatic configuration of Neos and TYPO3 environments. Roles for additional services and applications will follow.
Neos retrieves the environment-specific configuration files directly from the .env file.
Neos:
Flow:
persistence:
backendOptions:
driver: "%env:DB_DRIVER%"
dbname: "%env:DB_NAME%"
user: "%env:DB_USER%"
password: "%env:DB_PASS%"
host: "%env:DB_HOST%"
charset: "%env:DB_CHARSET%"
SwiftMailer:
transport:
type: Swift_SmtpTransport
options:
host: "%env:APP_SMTP_HOST%"
port: "%env:APP_SMTP_PORT%"
Configuration/Settings.yaml für Neos
If you have any questions about the project or need additional features, we'd love to hear your feedback—whether as comments here on the blog, as pull requests or issues on GitHub, or directly in the Neos Slack channel #proserver.
