tl;dr: To configure your proServer easily with Ansible, clone the template repository, copy the appropriate file from host_vars_examples to host_vars and adapt this and the inventory file for your proServer. Then start the provisioning with ansible-playbook. The playbook writes all configuration parameters to an .env file, which you can then use in your Neos project.
Hosting for Neos CMS projects
On the basis of the modern Neos CMS, even sophisticated and complex projects can be implemented on the web.
However, Neos itself is no less demanding when it comes to the right hosting environment. These are simple prerequisites, such as an identical and modern PHP version for CLI and PHP-FPM or the appropriate version of MariaDB as the database backend. If you want to fully utilize the features of Neos in larger projects, you also need server services that are not part of the standard portfolio of a normal hoster: Redis as a fast cache backend, Elasticsearch to manage and search 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 also constantly being adapted for future requirements.
"Infrastructure as code" with Ansible
Ansible is an automation tool for orchestrating and configuring servers. From a control node, Ansible connects to the target server via SSH and executes the commands required for configuration. No additional software is required on the target server for this. The Ansible configuration mainly consists of easy-to-read files in YAML format, which are used to define the tasks to be executed.
The advantages of configuring the server with Ansible code compared to manual configuration are obvious. All configuration steps are traceable and can be used at any time to configure new server instances identically. Of course, the Ansible code can be versioned just like the project code, so the infrastructure always matches the project exactly.
What is the proServer
With the proServer, we have created a hosting solution that has everything a sophisticated web project needs. Designed by our developers and tried and tested in our project business, the proServer should never get in the way of your daily work. It comes with an optimized standard configuration, which can be completely adapted to your own needs. At the same time, the installed software is updated regularly and automatically.
Technically, the proServer is based on FreeBSD and the container solution Jails. Each jail provides the environment for a complete project or just individual services. With our agency solution, proServer instances can be created at the touch 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 and put the Ansible roles we use to configure our instances as open source projects on Github. In this way, we want to make it even easier for our proServer customers to take their Neos projects live without much effort.
Each role encapsulates a role or a server service that needs to be configured. In addition to the standard services such as NGINX, php-fpm or database, there are also configurations that have proven to be very useful in our everyday project work, such as displaying the configured domains when logging in or an oAuth2 proxy to protect staging instances.
Configuring a proServer with Ansible
The following four steps are required to provision a proServer with Ansible.
1. Install Ansible
Ansible must first be installed on the local system. The Ansible Installation Guide contains various options for Unixoid systems. On Windows, Ansible can run in the Windows 10 subsystem for Linux.
2. Clone projects and submodules from GitHub
The GitHub project proServer-Ansible-Template summarizes the generic roles and the configuration for the specific project. The project and the roles used are cloned with this command:
git clone --recurse-submodules https://github.com/punktDe/proserver-ansible-template.git
3. Customize Ansible configuration for your project
The next step is to configure which proServer is to be configured with which roles and services. To do this, files must be adapted in two places.
host_vars
In the host_vars folder, we need a file for each host in our inventory that describes the specific parameters of this host.
Examples of such a file can be found under host_vars_examples. For a productive 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, the 0000 must first be replaced with your own proServer number at least everywhere. The configurations for the various services can then be adjusted according to your own 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. These groups are later used by Ansible to assign the necessary roles.
First, one of the host definitions must be commented in and the vpro number replaced. The server must then be assigned to the correct groups. For a productive Neos instance, for example, the line production is commented in under the key Neos.
host_vars Templates
We have created sample templates for the host_vars files in two variants for Neos and TYPO3. Templates for other services will follow.
The production.yaml contains the parameters for the stack from NGINX with let's encrypt SSL certificate, PHP, and either mariaDB or mySQL as database backend. In addition, the configuration for mail dispatch and the cluster name for the optional use of Elasticsearch are specified.
The staging.yaml also provides two useful services for staging environments.
The oAuth2 proxy protects the not yet productive site from unauthorized access. We have preconfigured gitlab as the backend for authentication, so you can easily authenticate via gitlab. Of course, other backends can also be used; examples can be found here.
Mailhog is the second service configured only for staging. With Mailhog, all mails sent from the CMS are automatically intercepted and can be displayed in a web interface. An API allows access to the mailbox - ideal for automated front-end testing with codeception, for example.
4. Start Ansible
Ansible is now configured for the first run and can be started. The following call, for example, 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 completely configured for a Neos instance. The Neos project is expected in the path /var/www/neos/current . A path that matches a project transferred with Deployer. An example configuration for a deployment of Neos with Deployer can already be found in our template project.
Bonus: Configure Neos automatically with .env
The Neos Ansible role not only takes care of configuring the NGINX for Neos. It also writes all important configuration variables such as the access data for the database or Elasticsearch to an .env file under /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. A distinction between staging and production in the configurations is also unnecessary. If services such as database servers or Elasticsearch are distributed to other hosts, the configuration adapts automatically without having to touch the project code.
The following commands are used 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 adjacent configuration then ensures that the parameters are read from the environment.
Our template project already contains the necessary roles and examples for the automatic configuration of Neos and TYPO3 environments. Roles for other services and applications are to follow.
Neos obtains 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 extensions, we are very happy to receive any feedback; as comments here in the blog, as pull requests or issues on GitHub or directly in the Neos Slack channel #proserver.
