This document is under active development and discussion!

If you find errors or omissions in this document, please don’t hesitate to submit an issue or open a pull request with a fix.

Preface

The WPN-XM server stack is a software bundle for web developers and a profound base for the development of web applications.

This book is a comprehensive guide to getting started and working with WPN-XM. It includes details of the installation, the architecture, folder layout and the different applications shipped and their default configurations.

WPN-XM provides a number of advantages:

  • multiple installers

    • the prepackaged installers ship software components as a bundle

    • the webinstaller allows the selection of components to download

  • two software catalogs to chose applications from

    • Stack components

    • PHP applications

  • all components are also available for selective manual download on our website

  • the updater

    • indicates updates for installed software components

    • allows to keep your stack up-to-date by updating already installed components

    • allows to install additional (not-yet-installed) components

  • it is a preconfigured development environment, ready to work out-of-the-box

  • Sever Control Panel

  • Webinterface

  • fully Open-Source

    • build using an open-source build toolchain

    • providing reliable and continuous open-source builds

WPN-XM has several goals:

  • convenient local web development environment with a focus on PHP

  • simple and fast installation

  • out-of-the-box configuration for servers

  • simple start and stop of servers

  • easy to start new projects

  • support for multiple user projects

  • seamless automatic updates

Reasons

There are already several server stacks for Windows out there. Why another one?

Just to name a few reasons:

  • Well, a PHP server stack like i imagined didn’t exist (until now :).

  • I love tooling and making things. Things which actually make it easier, to make new web technology things.

  • It’s about empowering more people to build more things.

  • Mainly because installing things on Windows isn’t straightforward. I wanted to save my life-time and the life-time of other developers by getting rid of the daunting, repeated tasks of searching for software and installing stuff manually. I imagined to build an environment, where pulling in new web development related packages and tools is easy. A system where all the hassle of settings things up is greatly reduced and everything is ready to work right out-of-the-box. The stack addresses the fundamental problem of Windows: the missing package management. But, only for a small subset of the software ecosystem: for software, relevant for web developers.

  • I started the project as a true open-source project, because other server stacks were (and are still) not really open-source.

  • The project solves the "i’m not in charge and cannot modify the project like i want" problem.

  • I’m trying to close the gap between third-party vendors, which provide tools and servers, and PHP. Mainly, because PHP’s support for these niche DB system is pretty bad. Example-wise, let’s take a look at database vendors: The combination of PHP and MySQL as RDBMS helped PHP to get used in lots of places and use-cases. But, nowadays, there are other interesting database solutions out there, including NOSQL, Graph, RDF and realtime databases.

  • Finally, let’s partly quote the auto maker Renault: i need to "drive the change".

1. Getting started

1.1. Requirements

1.1.1. Which Windows versions are supported by your installation wizards?

You can execute our installation wizard executables on nearly all Windows versions.

The installation wizards are Inno-Setup based. Inno-Setup supports every Windows release since 2000, including: Windows Server 2003, 2008, 2008 R2, 2012 and, Windows 2000, XP, Vista, 7, 8, 8.1, 10 . The installers do not require service packs.

1.1.2. Which Windows versions are supported by the packaged components?

We differentiate installers by bitsize. We build installers for x86 and x64 Windows versions and bundle components accordingly.

When bundling components our lowest supported Windows version is Windows 7.

Please take a look at the Windows compatibility of the components included in the installer.

We test installers for compatibility only on Windows 7 and Windows 10.

If you are running into a compatibility issue with one of the bundled components, please do not hesitate to inform us and report the problem over at Github Issues. Thank you!

1.1.2.1. List of supported Windows Versions
  • Windows 7 (32-Bit) Professional

  • Windows 7 (64-Bit) Home Premium and Professional

  • Windows 7 SP 1 (32-Bit) Home Premium, Professional, and Enterprise

  • Windows 7 SP 1 (64-Bit) Home Premium, Professional, Enterprise, and Ultimate

  • Windows 8 (32-Bit and 64 Bit) Core, Professional, and Enterprise

  • Windows 8.1 (32-Bit and 64 Bit) Core, Professional, and Enterprise

  • Windows 8.1 Update (32-Bit and 64 Bit) Core, Professional, and Enterprise

  • Windows 10

1.1.3. Minimum Requirements (todo)

  • OS

  • Processor

  • Memory

  • Storage

  • Additional Notes

  • OS

  • Processor

  • Memory

  • Storage

  • Additional Notes

1.2. Installation

This chapter explains how to install WPN-XM Server Stack for Windows.

The installation wizard packages for WPN-XM are available starting with version v0.1.0. The packages are available for the x86 (32 bit) and since v0.8.1 also for the x86_64 (64 bit) processor architecture. You can choose between two installer types: we provide packaged installers and web-installers. We package installers for every supported PHP version.

The following installer packages are available:

  • Lite & Lite-RC Installer

  • Standard Installer

  • Full Installer

  • Web-installer

The Standard and Full Installers contain a large set of components in one big setup executable. The Lite installer ships a minimal set of components to get you started. This version ships a stable PHP version. The Lite-RC installer is the Lite packages, but ships the latest PHP RC (Release Candiate) version for testing purposes.

The Web-installer is a small file you can use to select and download the components of your choice from the web. Pros: Instead of downloading one large installer containg all components, you are downloading the small web-installer and then only the components you select. This has the advantage of saving you time and bandwidth. You can also download and save the web-installer for later installation. Cons: The web-installer is a problem, when packages must go through a review process before installation. External links are often discouraged in this review process, because they require external calls during install and can make restoration of service difficult, when the links or the link targets change.

Important: If you face problems downloading certain components using the web-installer, please disable your Anti-Virus and re-try.

You might install WPN-XM either by using the common user interface or by installing it in silent mode. The silent mode is for integration with automatic and unmaintained installation procedures.

The following sections explain the installation wizard user interface. We’ll use screen-shots from an w64 installation on Windows 10 below.

1.2.1. Installation UI

Using the installation wizards user interface is the typical mode of installation.

To start the installer, just click on the setup executable, e.g. "WPNXM-0.8.6-Full-Setup-php56-w64.exe".

1.2.1.3. Custom Setup / Components Selection
WPN-XM Screenshot 3

On the Custom Setup Screen you might choose what software components and features to install.

The drop-down box will show you four default software component pre-selections you might choose from.

WPN-XM Screenshot 3 Preselection

The Lite installation wizard has only two pre-selection setups: Full and Custom. While all other installation wizards have four default preallocation setups:

  1. Full Installation

    • This preselects everything for installation.

  2. Server Stack with Administration Tools

    • Base (NGINX, MariaDB, PHP)

    • Admin Tools (Tray App, Webinterface)

    • Dependency Tool (composer)

  3. Server Stack with Debug Tools

    • Base (NGINX, MariaDB, PHP)

    • Admin Tools (Tray App, Webinterface)

    • Debug Tools (xhProf, XDebug, webgrind)

    • Dependency Tool (composer)

  4. Custom Installation

    • This deselects everything and you might choose freely.

1.2.1.4. Select the Startmenu Folder
WPN-XM Screenshot 4

You might select a folder or sub-folder of the start menu, where the WPN-XM start menu entries will then be created.

1.2.1.5. Select Additional Tasks
WPN-XM Screenshot 5

You might select various tasks to perform during installation, like creation of shortcuts in the start menu and on your desktop. If you install the files on a portable device, don’t forget to enable "Portable Mode".

1.2.1.6. Installation Running Screen
WPN-XM Screenshot 7

The screen shows the progress while downloading and installing the components for your WPN-XM stack.

1.2.1.7. End
WPN-XM Screenshot 8

Installation is finished now.

1.2.2. Start Menu Entries

After the installation finished, you will find the following new start menu entries:

WPN-XM Startmenu

Description of menu entries and what they do

  • Administration - Opens the Administration Webinterface of WPN-XM in your default Browser.

  • Report Issue - Opens the Issues Reporting Page of WPN-XM

  • Server-Control-Panel - Starts the Tray Application

  • Start - Starts all daemons and opens the webinterface your browser.

  • Status - Shows the status of all daemons in an endless loop.

  • Stop - Stops all daemons.

  • WPN-XM Server Stack in the Internet - Opens the official WPN-XM website.

1.2.3. Uninstallation

Simply execute the uninstaller program (unins???.exe) in the installation folder.

WPN-XM Uninstall Screenshot 1
WPN-XM Uninstall Screenshot 2

You’ll also find a shortcut in the start menu entries of WPN-XM.

1.2.4. Installation logs

If you encounter a bug in the installer, you might read the installer logs for diagnosis. You’ll find the logs in the installation folder, e.g. c:\wpnxm-server. The name of the log file is "Setup Log yyyy-mm-dd #num.txt", e.g. "Setup Log 2012-05-12 #005.txt". It’s a text file and you might open it with notepad or with the editor of your choice. Please attach the logs when creating bug reports.

1.2.5. Silent Installation & Unattended Installation

In our experience, the /silent switch is usually sufficient for a basic unattended installation. But to be completely sure, we recommend /sp- /silent /norestart as startup parameters.

There is also the parameter /verysilent. If you use /verysilent, my advise is to use the parameter /norestart as well, just to be sure that the machine will not reboot without prompting after or during the installation procedure.

You might also specify the target directory for the installation by using the parameter /dir, e.g. /dir="x:\dirname".

Using the pieces of information provided above, then a complete silent installation CLI call would look like this: *setup.exe /VERYSILENT /SP- /DIR="C:\INSTALL_DIR" /NORESTART.

The switches for Inno Setup Silent Installation are fully documented in the ISetup.hlp file in the Inno distribution.

1.2.6. Silent Uninstallation

The uninstaller program (unins???.exe) accepts optional command line parameters. You might use the parameters /verysilent and /norestart.

1.3. Files and Folders

This section describes the Files and Folders of the WPN-XM server stack after a successful installation. It refers to "c:\server\" as default location for the installation.

1.3.1. Files

File Installed with Component Description

c:\server\wpn-xm.exe

WPN-XM Server Control Panel

Executable of the WPN-XM Server Control Panel.

c:\server\start-wpnxm.bat

always

Batch file for starting all daemons.

c:\server\stop-wpnxm.bat

always

Batch file for stopping all daemons.

c:\server\reset-db-pw.bat

always

Batch file for resetting the MariaDB database password

c:\server\status-wpnxm.bat

always

Batch file for displaying the daemon state.

c:\server\start-mongodb.bat

MongoDB

Batch file for starting MongoDB

c:\server\stop-mongodb.bat

MongoDB

Batch file for stopping MongoDB

1.3.2. Folders

Folder Description

\bin\mariadb\

MariaDB executables, config and data.

\bin\mongodb\

MongoDB executables, config and data.

\bin\memcached\

Memcached executables.

\bin\nginx\

Nginx executable and config.

\bin\openssl\

OpenSSL executable and config.

\bin\php\

PHP executables and config.

\bin\sendmail\

Sendmail emulator executable and config.

\bin\tools\

Additional tools, e.g. RunHiddenConsole.

\temp\

Temporary folder. You might trash it from time to time.

\logs\

Log file folder.

\www\

The root folder for all web projects.

\www\tools\

The root folder for web-based administration tools.

\bin\nginx\conf\sites-enabled

The folder for all enabled Nginx domains. Place your server blocks here.

\bin\nginx\conf\sites-disabled

The folder for disabled Nginx domains.

1.4. Running

From the Start Menu you can startup the Server Control Panel:

WPN-XM Server Control Panel - MainWindow

After starting up the Server Control Panel, there is also a Server Control Panel icon in the right lower corner of the screen

WPN-XM Server Control Panel - TrayIcon

With the icon (using the right mouse button), you can also start and stop the servers.

WPN-XM Server Control Panel - TrayMenu

You need at least to start the Nginx and PHP daemon to get started. If you want to use a database connection you will also need to start the MariaDB daemon. Depending on your needs you can start, stop and restart other servers like MongoDB or Memcached. Or you can access the configuration, logs and error log files. When a daemon has been started, the status becomes green. If the status stays gray there is something wrong with the configuration of that daemon of the operating systems prevents that the IP ports gets opened or is already opened by another service (IIS for example) or daemon.

See FAQ page for some details about troubleshooting and how to solve problems.

For more details about the Server Control Panel, check this page.

1.5. Updating

The updater is work in progress.

1.6. Getting Help

There are several channels to reach the developers and the WPN-XM community to get direct assistance.

To find the right answers to your questions, you can turn to one of the following sources to get help and discuss your issues, but also to receive news and update notifications.

Github Issues

If you want to report a bug or contribute your ideas, you can use the WPN-XM Issue tracker on Github.

Twitter

Follow WPN-XM on Twitter to get real-time news regarding the development and to receive news and update notifications.

Forum

You might also join the WPN-XM community forums, where you can ask the community for help or report bugs and contribute ideas.

Stack Overflow

Scala is an active topic on Stack Overflow, a very popular programmer Q&A site.

Google+

We have an Google+ community that is a good place to discuss and learn about WPN-XM.

Mailing List

We also have a low-volume mailing list.

2. The Server Control Panel

2.1. About

The WPN-XM Server Control Panel is a GUI and CLI application, which enables you to control and configure servers on Windows easily.

The main window of the control panel provides start and stop, next to quick access buttons for logs and config files and indicates the process state, the used port and the software version for each server.

The control panel provides a tight integration with additionally installed tools, a self-updater, an updater for already installed software, a configuration dialog and a process viewer.

The following servers are supported: PHP, Nginx, MariaDb, MongoDb, Redis, Memcached, PostgreSQL.

It’s written in C++ using Qt 5.2+. It’s free and open-source software, released under GNU/GPL v3 license.

For the full list of features, see https://github.com/WPN-XM/server-control-panel#features

Breaking changes, new features, deprecations and bug fixes are tracked in the CHANGELOG.

2.2. Using the Server Control Panel

This section describes the usage of the Server Control Panel.

Server Control Panel - MainWindow

If the Server Control Panel is new for you please check the Running first before you continue reading.

When we look at the Server Control Panel more closely, you will see that it consists out of 6 parts:

Server Control Panel - MainWindow with Highlighted Parts

2.2.1. Part 1 - Project Buttons

Server Control Panel - Part 1
  1. Use this to visit the Home page of WPN-XM.org.

  2. Go to the WPN-XM mailing list.

  3. Report issue or request feature.

  4. Support the development of WPN-XM by donating.

2.2.2. Part 2 - Server Controls and Monitoring

Server Control Panel - Part 2

Start and stop the different daemons. Access the logs and error log files. Review and change configuration settings.

2.2.3. Part 3 - Tools

Server Control Panel - Part 3
  1. Show PHP information.

  2. Manage your databases using phpMyAdmin.

  3. Profiling in the browser using webgrind.

  4. Use adminer for the administration of different database systems like MySQL, MongoDB, SQLite and PostgreSQL.

2.2.4. Part 4 - Open Projects Folder

Server Control Panel - Part 4

Browse through your projects or open the explorer to work on your files.

2.2.5. Part 5 - Right Side Menu

Server Control Panel - Part 5
  1. Open Webinterface in Browser.

  2. Open the Configuration Panel.

  3. View Wiki help page.

  4. About window.

  5. Close the Panel (stays running in the background).

2.2.6. Part 6 - All Servers Start and Stop Buttons

Server Control Panel - Part 6

The buttons enable you to start or stop multiple servers at once. You can configure, which servers these buttons control in the configuration dialog.

2.4. Using the CLI

This section describes the usage of the Server Control Panel - Command Line Interface.

The Server Control Panel is a hybrid Windows application with two user-interfaces: the graphical user interface (GUI) and the command line interface (CLI).

When you run wpn-xm.exe without CLI arguments the application will start in GUI mode.

You can list the command line options by executing wpn-xm.exe --help. The following command line options are available:

WPN-XM Server Stack 0.8.5+0a7e025
Copyright (c) 2015 Jens-Andre Koch. All rights reserved.

Usage: wpn-xm.exe [option] [args]

Options:
-v, --version   Prints the version.
-h, --help      Prints this help message.
-d, --daemon    Executes on .
--start         Starts one or more .
--stop          Stops one or more .
--restart       Restarts one or more .

Arguments:
    The name of a daemon, e.g. nginx, mariadb, memcached, mongodb.
    The command to execute, e.g. start, stop, restart.

Examples:
    wpn-xm.exe --daemon nginx start
    wpn-xm.exe --start nginx php mariadb

Info: Ports specified in "wpn-xm.ini" will be used.

3. Software Components

3.1. Nginx

Nginx ("engine x") is a web server written by Igor Sysoev in 2002. It can act as a reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer and an HTTP cache. Nginx runs on Unix, Linux, BSD variants, OS X, Solaris, AIX, HP-UX, and Windows. Nginx is free and open source software and released under the terms of a BSD-like license.

3.1.1. Installation Location

The default installaton folder is server\bin\nginx.

3.1.2. Configuration

The main configuration file is nginx.conf in the folder server\bin\nginx\conf\.

The stack ships also a very minimal configuration for debugging purposes: nginx.conf.debug.

If you want to pass environment variables to PHP, you might set them as FGCI parameters (fastcgi_param) in the config.

For more advanced configuration examples take a look at the https://github.com/lebinh/nginx-conf repository.

3.1.3. SSL Configuration

You might use Mozilla’s SSL Configuration Generator to create a decent SSL configuration for Nginx. There are also Mozilla’s Server Side TLS Guidelines with more details on these configurations. If you need to test the configuration of a live servers you could use SSLLabs.

You might download the latest cacert bundle from here: - https://github.com/bagder/ca-bundle - https://curl.haxx.se/ca/cacert.pem

3.1.4. Server Blocks (sites-enabled and sites-disabled)

This main configuration file nginx.conf includes other configuration files from the folder server\bin\nginx\conf\sites-enabled. These configuration files are mostly server blocks. They contain directives to serve specific PHP applications, configure proxy forwarding or define application specific URL rewrite rules, which are needed to enable nice looking URLs without parameters.

The server stack ships several server blocks by default in the folder server\bin\nginx\conf\sites- disabled. To use one of these files, simply move or copy them to the server\bin\nginx\conf\sites- enabled folder and restart Nginx. The new server block configuration is then automatically included.

You find configuration files for various applications also on Github: https://github.com/WPN- XM/software/tree/master/nginx/config/conf/sites-disabled

3.1.5. root and server_name

The most important directives in a server block are root and server_name, next to the configuration of the rewrite rules for the specific application.

The root directive defines a relative path to the project, e.g. www/<my_project_folder>. But a hardcoded path will work too, e.g. c:\server\www\my_project_folder. The server_name directive defines which server block is used for a given request.

A very basic example for Wordpress: root www/wordpress and server_name wordpress.dev. This makes Wordpress available at the URLs http://localhost/wordpress and http://wordpress.dev. The URL http://wordpress.dev needs an additional entry in your hosts file.

Don’t forget to adjust your hosts file accordingly!

3.1.6. Defining an upstream pool and using "load balancing"

This section explains what an upstream pool is and how to configure it.

We start with a brief explanation on how web servers interface with servers that generate web pages dynamically. The web server itself doesn’t know about the language your are programming in. But how can the web server process and respond to requests for dynamically generated pages?

The web server communicates with a third-party server in a standardized way, which is either a gateway protocol or an embeded handler.

The Common Gateway Interface (CGI), a standard way for web servers to interface with executable programs installed on a server that generate web pages dynamically. CGI Version 1.1 is specified in RFC 3875 (actually it’s just a memo).

For processing PHP requests this CGI server is php-cgi.

For request processing Apache supports either CGI or mod_php or mod_fcgi, while Nginx supports fcgi.

Whats the difference?

3.1.6.1. CGI

The CGI approach means, that for every incoming request a new CGI process is spawned in the background to process the request, just to shut down at the end of processing. Process spawning consumes time and memory, while at the same time the PHP interpreter consumes time and memory for generating the output. This causes high workloads for servers, when multiple requests hit a website.

The overhead of process creation can be reduced by either using FastCGI or by running webserver extension modules, such as mod_php. With FastCGI interpreter processes are "preforked" and already exist for processing. With mod_php the interpreter is part of the web server and running as a webserver extension module.

3.1.6.2. MOD_PHP

The mod_php approach is probably the default way to combine PHP and Apache. Here the PHP interpreter is "embedded" inside the Apache process as "Module PHP". Based on the Apache config and especially your worker configuration, it will automatically spawn new workers (childs) to process the incoming requests. Apache handles worker respawns and multiple requests.

3.1.6.3. MOD_FCGI and FCGI ("prefork")

The mod_fcgi approach is also an Apache Module living inside the Apache process. It starts (preforks) a sufficient number instances of the CGI program to handle concurrent requests, and these programs remain running to handle further incoming requests.

The difference between Apache and Nginx in regard to FCGI handling is, that Apache manages the number of instances, while Nginx doesn’t. When using Nginx you have to make sure that the third-party FCGI servers are started and listening, that the number is sufficient to process your requests and that the servers are properly defined in Nginx’s upstream configuration.

Then requests are accepted by Nginx and forwarded to the external FCGI server for processing.

nginx fcgi request handling
3.1.6.4. Whats the difference between FCGI and CGI?

FCGI is basically CGI, but without the shutdown. The FCGI process is spawned once and stays in listening mode. The upside is that the response/request latency is lower than with CGI, leading to faster response times, because the "boot time" of CGI is gone and consuming less resources.

But, the downside is, that it is only one process. When multiple requests need to be processed, but the FCGI server is already processing a long running request, then the stack will "block".

Now, in order to handle even more requests: you could setup one or more Nginx processes accepting requests, which pass requests forward to one or more external FCGI servers, and these can also have childs. Example: 8 Nginx processes passing requests to a pool of 8 FCGI servers with 10 childs each.

3.1.7. Nginx "Load Balancing" algorithms

What’s the best "load balancing" configuration?

It’s hard to answer this question in general. There is no single best "load balancing" configuration, because it depends on your use-case. In order to compare configurations, you would need to come up with some alternative configurations, measure them under a high request load and finally compare the results to draw a conclusion.

Nginx provides numerous ways to configure the balancing:

For instance, you could use ip_hash to allow session persistence (for login/re-login), but hash key [consistent] has probably the same effect, but uses a different algorithm in the background (libketama).

When you just want to spread load across servers and the application has no demand for session consistency, then the default "round robin" balancing is better and faster, because it doesn’t spend time and resources on hashing a given key or client IP address.

3.1.8. Alternative Nginx Builds for Windows

The WPN-XM Server Stack uses Nginx builds from the offical website. But there are also some interesting private builds around. Sadly, their builds and build toolchains are not open-source, so the builds are completely private and re- building is not possible. Due to this fact, i can not include these builds into WPN-XM.

You have the choice to download them on your own risk and simply replace WPN-XM’s Nginx folder.

3.1.8.1. Official Nginx - http://nginx.org/

This is the offical Nginx Windows build from the main nginx website. We ship this one by default.

3.1.8.2. Nginx-Win - http://nginx-win.ecsds.eu/

This is an unofficial private build. The source for the build, patches and adjusted modules and toolchain are not open-source. The build includes lots of performance tweaks, additional modules compiled in and multi-worker support. For instance, support for SPDY, rtmp, LUA, Naxsi WAF was added.

My request to open-source the toolchain for builds on Travis-Ci and for cooperation was denied.

The real name of the author is unknown. His nickname "itpp2012" on the Nginx mailing-list and Nginx related discussion Forums. His Github Account is: https://github.com/itpp16

3.1.8.3. Nginx for Windows - http://kevinworthington.com/nginx-for-windows/

This is an unoffical private build. The x32 and x64 builds are using Cygwin. The build toolchain is not open-source.

3.1.8.4. OpenResty - https://openresty.org/

OpenResty is a scalable Web Platform by extending NGINX with Lua. The auther is Yichun Zhang (agentzh).

3.1.9. Nginx Catch-All *.dev domains

This is a catch all configuration, which maps all project folder names to .dev domains.

server {
    listen 80;

    server_name ~^(.*)\.dev$;
    set $file_path $1;

    root /www/$file_path/public

    index index.php index.html

    # etc.
}

Then create a index.php file in a new project folder www\myproject with the content <?php echo 'Hello from folder: ' . DIR;.

Now, update your hosts file accordingly and include myproject.dev.

Done. You can now access myproject.dev in your browser.

3.2. MongoDB

MongoDB (from humongous) is a free and open-source cross-platform document-oriented database. It’s a popular NoSQL database.

32-bit Limitations

The 32-bit versions of MongoDB have the following limitations:

  • no support for the WiredTiger storage engine,

  • disabled journaling, because journaling further limits the maximum amount of data that the database can store,

  • the total storage size for the server, including data and indexes, is 2 gigabytes. For this reason, do not deploy MongoDB to production on 32-bit machines.

If you’re running a 64-bit build of MongoDB, there’s virtually no limit to storage size. For production deployments, 64-bit builds and operating systems are strongly recommended.

See here for more information.

Please check MongoDB’s Getting Started guide for more!

3.2.1. PHP Extension for Mongo

To access MongoDB from PHP you need two things:

the MongoDB server mongod running and the PHP driver installed.

3.2.1.1. Driver Compatibility

The old and legacy MongoDB PHP driver is mongo, while the new driver is mongodb. For a detailed overview please see the PHP Driver Compatibility Table.

3.3. MariaDB

MariaDB is a community-developed fork of the MySQL relational database management system and a drop-in replacement for MySQL. The project was forked due to concerns over the MySQL acquisition by Oracle Corporation. The development is led by some of the original developers of MySQL - including Michael "Monty" Widenius. MariaDB is named after Monty’s younger daughter Maria, similar to how MySQL is named after his other daughter My.

3.3.1. Installation Location

The default installaton folder is server\bin\mariadb\.

3.3.2. Configuration

The main configuration file is my.ini in the folder server\bin\mariadb\.

3.4. PHP Extensions for MariaDb

The PHP connectors for MySQL generally work with MariaDB as well. It is recommended to use either the mysqli or PDO_MySQL extensions. See http://php.net/manual/en/mysql.php

3.5. PostgreSQL

PostgreSQL is an object-relational database management system (ORDBMS) based on POSTGRES, Version 4.2, developed at the University of California at Berkeley Computer Science Department. POSTGRES pioneered many concepts that only became available in some commercial database systems much later.

3.5.1. Connection data

The most GUI applications will expect you to provide the following connection parameters to connect:

Host

localhost

Port

5432 (default)

Username

root

Password

blank

Database

yourdb

If you need to provide an URL, use postgresql://username@localhost/yourdb.

Username on WPN-XM versions below v0.8.7

WPN-XM versions below v0.8.7 did not set a username during the installation and initial setup of PostgreSQL with initdb. For these installs initdb created a table named "postgres" owned by user "current logged in user name", which is/was the user running the installer.

When calling commands on the CLI, please leave the -U or --username CLI arguments away, so that the default username is used.

Starting with WPN-XM v0.8.7 the default username is "root".

When calling commands on the CLI, please use -U root or --username=root .

3.5.2. First steps after installation

Please use the interactive terminal application pgsql to make your first steps.

You find detailed instructions in the PostgreSQL manual (https://www.postgresql.org/docs/current/static/app-psql.html).

  1. Switch to the folder c:\server\bin\pgsql

  2. run psql --version to show the version

  3. run psql --list -U root to list the databases

                            List of databases
   Name    |  Owner | Encoding |   Collate   |    Ctype    |   Access privileges
-----------+--------+----------+-------------+-------------+-----------------------
 postgres  | root   | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
 template0 | root   | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +
           |        |          |             |             | postgres=CTc/postgres
 template1 | root   | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +
           |        |          |             |             | postgres=CTc/postgres
(3 rows)
  1. run psql --username=root --dbname=postgres to edit the postgres table using the interactive console

c:\server\bin\pgsql\psql --username=root --dbname=postgres
 psql (9.6.0)
 Type "help" for help.

Run help:

postgres=#  help
 You are using psql, the command-line interface to PostgreSQL.
 Type:  \copyright for distribution terms
        \h for help with SQL commands
        \? for help with psql commands
        \g or terminate with semicolon to execute query
        \q to quit

3.5.3. Support for JSON and JSONB

The storage format for json is plain text format, while it is a binary representation for jsonb.

It takes more time to create the binary representation from the input representation (jsonb is slower, than json). and it takes more disk space to store than json (jsonb uses more space, than json).

The parsing of json has to be repeated, for each operation at a json value.

json operations take significantly more time than jsonb. In other words: jsonb is faster for operations on JSON value(s).

To sum up:

When to use JSON or JSONB?*

Use JSON, if you only work with the JSON representation in your application, which is stored and retrieved. Use JSONB, if you do a lot of operations on the JSON value(s), or use indexing on some JSON field.

3.5.4. GUI Clients

The official GUI client is pgAdmin and ships with PostgreSQL. But there are many GUI clients for PostgreSQL. You can find many of them in the https://wiki.postgresql.org/wiki/Community_Guide_to_PostgreSQL_GUI_Tools [Community Guide to PostgreSQL GUI Tools] in the PostgreSQL wiki.

3.6. PHP

3.6.1. Installation Location

The default installaton folder is server\bin\php.

3.6.2. Working with multiple PHP versions

You can install multiple version of PHP into the \bin folder, e.g. \bin\php-5.6.1 next to bin\php.

You might use the PHP version switcher of the webinterface to switch between versions.

The PHP version switcher does two things. Firstly, the version number in the bin\php folder is determined, then the folder is renamed accordingly, e.g. bin\php-1.2.3. Secondly, it renames the folder of the selected version (the one it should switch to) from bin\php-1.2.3 to bin\php.

The PHP interpreter in the bin\php folder is the active and used one, when multiple version of PHP are installed.
Please keep in mind that configuration and installed extensions might differ!

3.6.3. What does NTS and TS mean?

NTS and TS are abbreviations for non-thread safe and thread-safe.

Both processes and threads are independent sequences of execution.

The difference is that threads (of the same process) run in a shared memory space, while processes run in separate memory spaces.

Code is thread-safe, when modifications of data structures in the shared memory are guaranteed to be safely executed from multiple threads. A safe execution is achieved by avoiding race-conditions and deadlocks, for instance, by means of synchronization between the threads. A deadlock occurs when many processes execute no further because they are waiting for a shared resource, which is being used and held by another process.

3.6.4. PHP Bitsizes

Note on the PHP 64bit releases:

PHP 5.x provides experimental 64-bit support.

The x64 builds of PHP 5 for Windows are experimental, and do not provide 64-bit integer or large file support. It has has memory limitations (max. memory = 2047M). No matter the architecture, a long value is always 32bit. This behavior of PHP is expected and known for a long time.

PHP 7 provides full 64-bit support.

The x64 builds of PHP 7 support native 64-bit integers, LFS, memory_limit and much more.

3.6.5. Configuration

The default configuration file for PHP is server\bin\php\php.ini.

There is a minimal configuration file for Composer runs server\bin\composer\php.composer.ini. Please check the Composer chapter.

3.7. PHP Extensions

3.7.1. Installation Location

The default installaton folder for extensions is server\bin\php\ext.

3.8. Pickle

Pickle is a cross-platform PHP Extension installer.

3.8.1. Usage

For example, to install the memcache extension run the following command:

$ pickle install memcache

Its also possible to require a specific version:

$ pickle install <extension>@<version>

3.9. PEAR

The PHP Extension and Application Repository (PEAR) is a package archive with over 600 packages: https://pear.php.net/packages.php

It provides a global installation method for vendor dependencies. Installed dependencies are then available for multiple applications.

PEAR support is deprecated. The last WPN-XM version shipping PEAR install scripts is v0.8.6.

The PEAR approach will cause problems, when different applications depend on different versions of a global dependency.

With the creation and adoption of Composer, the PHP community ditched the global installation method and switched to a per project folder installation of vendor dependencies.

Various tools and applications have deprecated the PEAR installation method.

3.9.1. Installation Script

WPN-XM provides the installation helper server/bin/php/go-pear.bat.

Please execute the batch file and follow the instructions displayed on screen. The instructions will guide you through the PEAR installation process.

3.9.2. Instructions

Please use this answer set, to go quickly through the installation of PEAR.

  • Are you installing a system-wide PEAR or a local copy? Type local and press Enter.

  • Please confirm local copy by typing 'yes': Type yes and press Enter.

  • Press 1.

  • Use the folder selection dialog and select your "WPN-XM installation folder/bin/php/PEAR".

  • You will see the same dialog, but with adjusted paths. Press Enter.

  • Would you like to alter php.ini? Type yes and press Enter.

  • Configuration file paths are shown. Press Enter. Congrats!

3.10. Composer

Composer is a CLI tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

All our installers ship Composer out-of-the-box.

3.10.1. Installation Location

The default installaton folder is server\bin\composer.

The folder contains two files: composer.phar and composer.bat.

3.10.2. Configuration

The installer will set server\bin\composer to the ENV PATH.

This makes composer.bat available system-wide.

3.10.3. Usage

To run Composer on the CLI type

composer.

3.10.4. PHP Configuration for Composer

Users often ask "How to disable Xdebug for Composer runs on the CLI?".

We provide a separate, minimal PHP configuration file for Composer runs. The file is named php.composer.ini. Whenever you invoke composer.bat or run composer on the CLI, the minimal config will be used to start PHP, before Composer is started. The purpose of this config is to run Composer, without xDebug in order to speed it up.

Why?

There is a huge impact of just loading Xdebug. It slows the Composer run down by 3x or 4x, even when the profiling feature is not enabled. In other words: xdebug is invaluable for debugging, but increases the memory used and processing time of Composer. See https://getcomposer.org/doc/articles/troubleshooting.md#xdebug-impact-on-composer

3.10.5. Official Windows Installer

The server stack doesn’t use the official Windows Installer.

Further instructions for Composer’s Windows installer can be found within the README.

3.11. Redis

Redis is an open source (BSD licensed), in-memory data structure store, used as database, cache and message broker. It supports data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs and geospatial indexes with radius queries.

Redis has built-in replication, Lua scripting, LRU eviction, transactions and different levels of on-disk persistence, and provides high availability via Redis Sentinel and automatic partitioning with Redis Cluster.

3.11.1. Installation Location

The default installaton folder is server\bin\redis.

3.11.2. Configuration

Redis config is located at \server\bin\redis\redis.conf.

3.11.3. Working with Redis from PHP

Redis is an independent server, which can be called by any other process. This calls for a bridge between the calling process and the Redis service.

In other words: you need a PHP client to interact with Redis. This client is either a PHP extensions or a PHP library.

There are several to chose from: http://redis.io/clients#php

3.11.4. Working with Redis from Node

A redis client for for Node.js is Mranney’s "Node Redis". - https://github.com/NodeRedis/node_redis

3.11.6. Redis compared to Memcached

Both Redis and Memcached are data cache systems and open source. Redis allows to store abstract data types, while Memcached stores only strings. Redis has snapshotting and journaling capabilites, which means that saved data stays even after a system restart, while Memcache’s memory stored-data is lost. Memcached is basically a memory store for short-lived data. Redis provides several fine-tuning options and features like advanced memory management and a better data eviction control.

3.12. Memcached

Memcached is a free & open source, high-performance, distributed memory object caching system, generic in nature, but intended for use in speeding up dynamic web applications by alleviating database load.

Its an in-memory key-value store for small chunks of arbitrary data (strings, objects) from results of database calls, API calls, or page rendering. Memcached is a developer tool, not a "code accelerator" nor a database middleware.

Its is a simple key/value store. The server does not care what your data looks like. Items are made up of a key, an expiration time, optional flags, and raw data. It does not understand data structures; you must upload data that is pre-serialized. Some commands, like incr or decr may operate on the underlying data, but in a simple manner.

Memcached is, by default, a Least Recently Used cache. Items expire after a specified amount of time.

3.12.1. Installation Location

The default installaton folder is server\bin\memcached.

3.12.2. Configuration

Memcached doesn’t have a config file.

The default configuration is the creation of a 64MB memory pool and listening on port 11211.

3.12.2.1. Memcached CLI

You might print the list of available CLI options using

C:\server\bin\memcached>memcached.exe -h

Result:

memcached 1.4.5_4_gaa7839e
-p <num>      TCP port number to listen on (default: 11211)
-U <num>      UDP port number to listen on (default: 11211, 0 is off)
-s <file>     UNIX socket path to listen on (disables network support)
-a <mask>     access mask for UNIX socket, in octal (default: 0700)
-l <ip_addr>  interface to listen on (default: INADDR_ANY, all addresses)
-d            run as a daemon
-r            maximize core file limit
-u <username> assume identity of <username> (only when run as root)
-m <num>      max memory to use for items in megabytes (default: 64 MB)
-M            return error on memory exhausted (rather than removing items)
-c <num>      max simultaneous connections (default: 1024)
-k            lock down all paged memory.  Note that there is a
              limit on how much memory you may lock.  Trying to
              allocate more than that would fail, so be sure you
              set the limit correctly for the user you started
              the daemon with (not for -u <username> user;
              under sh this is done with 'ulimit -S -l NUM_KB').
-v            verbose (print errors/warnings while in event loop)
-vv           very verbose (also print client commands/responses)
-vvv          extremely verbose (also print internal state transitions)
-h            print this help and exit
-i            print memcached and libevent license
-P <file>     save PID in <file>, only used with -d option
-f <factor>   chunk size growth factor (default: 1.25)
-n <bytes>    minimum space allocated for key+value+flags (default: 48)
-L            Try to use large memory pages (if available). Increasing
              the memory page size could reduce the number of TLB misses
              and improve the performance. In order to get large pages
              from the OS, memcached will allocate the total item-cache
              in one large chunk.
-D <char>     Use <char> as the delimiter between key prefixes and IDs.
              This is used for per-prefix stats reporting. The default is
              ":" (colon). If this option is specified, stats collection
              is turned on automatically; if not, then it may be turned on
              by sending the "stats detail on" command to the server.
-t <num>      number of threads to use (default: 4)
-R            Maximum number of requests per event, limits the number of
              requests process for a given connection to prevent
              starvation (default: 20)
-C            Disable use of CAS
-b            Set the backlog queue limit (default: 1024)
-B            Binding protocol - one of ascii, binary, or auto (default)
-I            Override the size of each slab page. Adjusts max item size
              (default: 1mb, min: 1k, max: 128m)
3.12.2.2. run.bat

The batch file uses the following command to start Memcached:

`memcached.exe -p 11211 -U 0 -t 2 -c 2048 -m 2048`.

This means Memcached will listen on - TCP port 11211, - but not on UDP and - will use 2 threads, - accept a maximum of 2048 simultaneous connections and - use 2048 megabytes max memory.

3.12.2.3. PHP extension

There is a Memcached client written in C as a PHP extension.

3.13. Go Git Service (gogs)

Go Git Service is a self-hosted Git service written in Go.

3.13.1. Installation Location

The default installaton folder is server\bin\gogs.

3.13.2. Configuration

The custom user configuration file is located at \server\bin\gogs\custom\conf\app.ini.

There is also a main configuration file located at \server\bin\gogs\conf\app.ini.

Do not modify the main config. Make your modifications to the custom config. The user config values replace any prior values from the main config. That allows a seemsless updates to new Gogs versions, which might ship new configuration directives in their new main config file.

3.13.3. Running Go Git Service

3.13.3.1. Server

By default the server runs at http://localhost:3000/

3.13.3.2. Nginx Server Block

The is a default Nginx server block configuration file go-git-service.conf. Nginx will accept requests at http://gogs.dev forwarding them to http://localhost:3000/ internally.

4. PHP Applications

4.1. Drupal 7

Drupal is a PHP content management software. Initially written in the year 2000 by two University of Antwerp students, Dries Buytaert and Hans Snijder. The first release was in Januar 2001.

Nowadays the development is driven by Acquia Drupal and a vibrant open-source community.

Drupal 7.0 was released on January 5, 2011 (after being in development since July 2008).

4.1.1. Installation

The following step-by-step tutorial guides you through the process of installing and setting up Drupal 7.

The first few steps cover the installation of Drupal into the folder server\www\drupal7. Our goal is to have a working Drupal 7 installation accessible at http://localhost/drupal7/.

  1. Download: https://ftp.drupal.org/files/projects/drupal-7.42.zip

  2. Extract into server\www folder

    • Drupal brings its own folder: drupal-7.42. Simply rename it to drupal7.

  3. Open in browser: http://localhost/drupal7/install.php

  4. Select "standard"

  5. enable PHP Extension "gd"

    • php.ini: extension=php_gd2.dll

  6. create database with Adminer

  7. use the "database", "user" and "pw" in the Drupal installation dialog

  8. follow dialog and configure site

Finally Drupal is installed.

The URL is http://localhost/drupal7/ and the installation folder is server\www\drupal7

The next few steps cover how to get of the http://localhost domain and enable a shorter and more nice appealing local development domain instead.

4.1.2. Setup local domain http://drupal7.dev/

Apache users refer to this as setting up a "virtual host". Nginx doesn’t know what "virtual hosts" are With Nginx we simply define a new "server block" and use a server_name directive.

WPN-XM ships several "server block" configurations by default. You find them in the server\bin\nginx\config\conf\domains-disabled\ folder.

  1. copy the drupal7.conf from the domains-disabled to the domains-enabled folder

  2. edit the file and check that the following directives are defined:

    • root www/drupal7;

    • server_name drupal7.dev;

  3. then add a new "vhost" by using the Server Control Panel

    • right-click on the Tray

    • then click "Manage Hosts"

    • click "Add"

    • enter "127.0.0.1" and "drupal7.dev"

    • click "OK" and again "OK" (this changes your local hosts file)

  4. restart Nginx

  5. finally, open the URL http://drupal7.dev/

4.1.3. Enabling clean URLs for Drupal 7

  1. Open http://drupal7.dev/

  2. login

  3. To enable clean urls go to Configuration ▸ Clean-Urls or directly to

  4. enable checkbox "enable clean urls", then submit the form

  5. finally, open any clean URL, e.g. http://drupal7.dev/admin/content

We successfully installed Drupal 7 into server\www\drupal7, created a local server domain drupal7.dev and enabled clean URLs.

Colophon

© 2015 - 2016 Jens A. Koch

License

WPN-XM User-Manual by Jens A. Koch is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

You find the full license text here: https://creativecommons.org/licenses/by-sa/4.0/legalcode

License Summary

Creative Commons - Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)

You are free to
Share

copy and redistribute the material in any medium or format

Adapt

remix, transform, and build upon the material

for any purpose, even commercially.

The licensor cannot revoke these freedoms as long as you follow the license terms.

Under the following terms
Attribution

You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.

ShareAlike

If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.

No additional restrictions

You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

Notices

You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.

No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.

Authors

Chapter Page Author

Chapter 1

Running

Peter Vandenberghe

Chapter 1

Installation

Peter Vandenberghe

Chapter 2

Using the Server Control Panel

Peter Vandenberghe