3W CMS Documentation

Requirements

This document describes the requirements to work with CMS 5.0

Software versions

  • OS: Linux
  • PHP: 7.3
  • Composer: >= 2.0
  • NodeJS: >= 10.22.1
  • Yarn: >= 1.22.0
  • docker: >= 20.10.1
  • docker-compose: >= 1.22

Git

All git repositories are hosted at https://gitlab.3wmedia.nl/. Your personal SSH keys can be saved in your personal account within Gitlab.

Authentication

Composer

We run a private PHP package registry at https://packages.3wmedia.nl/ protected by basic auth. Use the following command to configure your access to this registry:

composer config --global http-basic.packages.3wmedia.nl w3media <password>

NodeJS

Warning: the NodeJS version might change later on. The easiest solution is to install NVM (https://github.com/nvm-sh/nvm) and install/configure NodeJS v10 as your default version. This will allow you to switch easily per project in the future.

We run a private npm package registry at https://npm.3wmedia.nl/ to host our version of @fortawesome fonts. Use the following commands to configure your access to this registry:

npm config set "@fortawesome:registry" https://npm.3wmedia.nl/
npm config set "//npm.3wmedia.nl/:_authToken" <auth-token>

Docker server

We’ve prepared a set of docker containers to easily work with various projects and services locally. This repository is located at: ssh://git@gitlab.3wmedia.nl:222/lib/docker-server.git This setup contains the follow tools:

Traefik

TCP/HTTP proxy which will route all traffic to the right container.

Apache/Nginx

Webserver to serve the application. Every application we run in development will use the hostname <application>.php<version>.cms. E.g. trekkershutten.php73.cms. When you access <application>.php<version>.cms apache will look for an application in /var/www/app/<application>.

PHP 5.6/7.3/7.4

Multiple PHP version containers are running. Based on the hostname suffix (.php<version>.cms) it will be routed to the correct version.

MySQL/MySQL-strict

We are running 2 versions of MySQL wich are configured differently.

MySQL runs on the host port 3306 MySQL-strict is running on port 3307

PhpMyAdmin

To access PhpMyAdmin you can access:

https://pma.php73.cms/ - access MySQL https://pmastrict.php73.cms - access MySQL strict

Mailhog

Locally test and debug emails

DnsMasq

Dnsmasq can optionally be used to simplify your hosts file in development. Instead of adding each host to your hosts file, we can globally link a suffix like .localhost or .cms to 127.0.0.1. Next to these global suffixes you will need at least the following hosts in your hostsfile, so your host machine will resolve docker container hostnames to localhost (for example when you are running a doctrine console command on your host machine, it will need to be able to resolve mysqlstrict hostname outside of the docker container):

127.0.0.1 apache
127.0.0.1 mailhog
127.0.0.1 mysql
127.0.0.1 mysqlstrict
127.0.0.1 nginx
127.0.0.1 php56
127.0.0.1 php73
127.0.0.1 php74
127.0.0.1 php80
127.0.0.1 pma
127.0.0.1 pmastrict
127.0.0.1 varnish

Using DnsMasq

DnsMasq is running as a docker container with a static IP 172.33.0.100. By default, the docker containers will use this container to resolve DNS (see dns: lines in docker-compose.yml). But, your system will not use this service to resolve DNS by default. Here we will explain how you can configure it:

Checking DNS resolve

First we will check the current results of DNS resolve

dig +short non-existing-domain.php73.cms # resolved by the host machine, probably no output, because DNS resolve will fail
dig +short @172.33.0.100 non-existing-domain.php73.cms # resolved by the container, should output 172.33.0.1 (docker network IP)
Configuring DNS resolve on your system

Depending on your linux distribution there are some variations on how to configure DnsMasq.

a) /etc/resolv.conf

The easiest way should be to add the DnsMasq docker container static IP address to /etc/resolv.conf. Here is an example config using DnsMasq as primary and Google DNS as fallback DNS:

nameserver 172.33.0.100
nameserver 8.8.8.8
nameserver 8.8.4.4
b) NetworkManager built-in dnsmasq

Newer versions of systemd NetworkManager have a built-in dnsmasq. If this directory exists it should be available: /etc/NetworkManager/dnsmasq.d First, you need to enable this built-in DnsMasq. Make sure the following lines are present in /etc/NetworkManager/NetworkManager.conf.

[main]
dns=dnsmasq

Next, you can copy the host.conf version of the 3wserver dnsmasq config to your NetworkManager dnsmasq config directory

cp ~/server/data/config/dnsmasq/host.conf /etc/NetworkManager/dnsmasq.d/
c) Run DnsMasq on your host system

If your NetworkManager does not have a built-in dnsmasq service you can also install and run dnsmasq on your system. Example to install and run it on a debian-based distro:

sudo apt install dnsmasq
sudo systemctl enable --now dnsmasq

Depending on your distro the dnsmasq config directory will be located somewhere like /etc/dnsmasq.d/. Again, you can copy the host.conf version to this directory

cp ~/server/data/config/dnsmasq/host.conf /etc/dnsmasq.d/
Enabling and testing DNS resolve

In order to enable the new configuration you should restart the corresponding services. When you used version a) or b) you should restart the NetworkManager service by executing:

sudo systemctl restart NetworkManager

When you used version c) you should restart both dnsmasq and NetworkManager

sudo systemctl restart dnsmasq
sudo systemctl restart NetworkManager

Now we can test DNS resolve again to see if the DNS resolve of your host machine can now resolve local domains:

dig +short non-existing-domain.php73.cms # should output 127.0.0.1

Troubleshooting DNS resolve

/etc/resolv.conf overwritten

WARNING: the systemd NetworkManager might (depends on configuration/version) replace the contents of /etc/resolv.conf on a service/system restart. To prevent this from happening, you can make the /etc/resolv.conf file immutable after modifying it with the following command:

sudo chattr +i /etc/resolv.conf

In order to make it mutable again (if you need to make a modification), you can execute (don’t forget to make it immutable again after modifying):

sudo chattr -i /etc/resolv.conf
DNS resolve errors

Use the following command to find errors

docker logs dnsmasq
sudo systemctl status NetworkManager
sudo systemctl status dnsmasq
DnsMasq port 53 conflict

When you tried to use solution c) it is possible that dnsmasq can’t start because port 53 is already in use. This is because of the NetworkManager “DNSStubListener”, you can disable it by:

sudo systemctl stop systemd-resolved.service
sudo systemctl disable systemd-resolved.service

Next edit /etc/systemd/resolved.conf, and make sure this line is present

DNSStubListener=no

Next, edit /etc/NetworkManager/NetworkManager.conf, and make sure this line is present in the [main] group

dns=default

Finally, restart the NetworkManager and dnsmasq service again

sudo systemctl status NetworkManager
sudo systemctl status dnsmasq