proServer Ansible Template

This repository contains Ansible playbook examples for your proServer. It depends on our open open source Ansible roles, which are included as submodules. As of now, there are two supported applications:

• Neos
• TYPO3

There are several components (roles):

Relational databases

• PostgreSQL
• MySQL / MariaDB

Full text search databases

• Elasticsearch
• Apache Solr

In-memory databases

• Redis

Web servers

You can choose which web server to install by adding your host to the respective group (apache or nginx) in inventory.ini. Default is nginx

• nginx
• Apache

Mail servers

• Sendmail (for production)
• MailHog (for testing)

Other components

• System (base system configuration)
• PHP and PHP-FPM
• Supervisor (to manage custom daemons)
• OAuth2 Proxy (for advanced access control)
• Dehydrated (for acquiring X.509 certificates using ACME / Let's Encrypt)

Getting Started

1) Clone this repository

git clone https://github.com/punktDe/ansible-proserver-template.git
cd ansible-proserver-template

2) Install Ansible on your local machine. Ansible >=2.15 should work. See the Ansible Installation Guide for detailed instructions for your operating system. If you have Python 3 and venv installed, you can use this command:

python3 -m venv venv
venv/bin/pip install -r requirements.txt
source .envrc 
ansible-galaxy install -r requirements.yml

You can also use direnv to automatically activate the virtual environment and install dependencies when you enter the project folder.

4) Adapt Ansible configuration

Basically there are two files, that define the services and configuration for your proServer instance:

inventory.ini

Your inventory contains a list of hosts (proServers) and the groups each host belongs to. The groups are later used by the playbook to determine which roles (applications and components) to provision on a host.

Replace at least any occurrence of vpro0000 with your proServer ID(s) and uncomment staging/production within the application groups section.

host_vars/

The host_vars directory contains a number of files, each file represents a host from your inventory. You can copy examples from the host_vars_examples directory. development.yaml represents the development environment (Vagrant+VirtualBox).

mv host_vars_examples/neos/* host_vars/

Then replace at least any occurrence of vpro0000 with your proServer ID(s).

Secret management

We recommend using bitwarden-cli to manage secrets.

After setting up the CLI client, replace the placeholder in vault_password_file_example with the name of the password in your Bitwarden vault, and rename the file to vault_password_file.

It's also possible to use another password manager or a secret management system, as long as it can output the secret in plaintext.

Alternatively, you can remove the executable bit from vault_password_file and put your vault password in clear text. However, this is not recommended.

Start provisioning of your proServer

ansible-playbook --ssh-extra-args=-oProxyJump=jumping@ssh-jumphost.karlsruhe.punkt.de --limit=staging playbook.yaml

Replace --limit=staging with --limit=production to provision the production environment. You can also remove the limit parameter to provision all environments from your inventory.ini.

Neos configuration hints

The neos role will template the file /usr/local/etc/neos.env, which contains useful information about your environment (e.g. domain name, database type and credentials). You can use the helhum/dotenv-connector package to read the file and use any variable it contains in your Neos configuration.

composer require helhum/dotenv-connector
composer config extra.helhum/dotenv-connector.env-file /usr/local/etc/neos.env

# Configuration/Settings.yaml
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%"

TYPO3 configuration hints

The typo3 role will template the file /usr/local/etc/typo3.env, which contains useful information about your environment (e.g. domain name, database type and credentials). You can use the helhum/dotenv-connector package to read the file and use any variable it contains in your TYPO3 configuration.

composer require helhum/dotenv-connector
composer config extra.helhum/dotenv-connector.env-file /usr/local/etc/typo3.env

# htdocs/typo3conf/AdditionalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['dbname'] = getenv('DB_NAME');
$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['user'] = getenv('DB_USER');
$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['password'] = getenv('DB_PASS');
$GLOBALS['TYPO3_CONF_VARS']['DB']['Connections']['Default']['host'] = strpos(getenv('DB_HOST'), ':') === false ? getenv('DB_HOST') : '[' . getenv('DB_HOST') . ']';
$GLOBALS['TYPO3_CONF_VARS']['SYS']['trustedHostsPattern'] = getenv('SITE_DOMAIN');

Deployment

Deployer can be used to deploy Neos or TYPO3 to a proServer. deployer_examples/ contains a set of Deployer configuration examples.

Helpful links

• Ansible Installation Guide
• Ansible Getting Started