Let's say you manage some websites or other network servers, and you wish to monitor them. You decide it's time to install and operate a Server Monitor to help with that task. There are quite a number of server monitors available from which to choose. At this time you choose a basic, easy-to-use server monitor named PHP Server Monitor:
PHP Server Monitor may be installed on a shared host or a VPS. If your shared host or VPS is already configured to serve websites, all of the services PHP Server Monitor requires are often already installed. If the services it needs are already installed, you do not need to use Php-Server-Mon-Sys; the default method of installing PHP Server Monitor is probably required on a shared host, and is probably preferred on a VPS.
However, if your host does not already have the required services installed, you now have a problem. The problem is, installation of the required services may be complicated and time consuming.
Php-Server-Mon-Sys solves this problem. In many cases, Php-Server-Mon-Sys makes installation of PHP Server Monitor much faster and simpler on hosts which do not already have the required services installed.
In addition to installing PHP Server Monitor, Php-Server-Mon-Sys installs the required services. Php-Server-Mon-Sys includes NGINX, MySQL, and PHP-FPM. These are "private" services which are available only to PHP Server Monitor. These services are not installed directly into the host operating system per usual. These services are deployed using Docker containers. Using Docker containers means these services may be very easily and cleanly installed and un-installed along with the PHP Server Monitor application software. Backing up and restoring are also quick and uncomplicated.
When you no longer need the PHP Server Monitor software in your system, you may very easily remove it. When it is removed, PHP Server Monitor's supporting services are removed as well. There is no need to individually remove each of the other services no longer needed.
Keep in mind that the NGINX, MySQL, and PHP-FPM services which are installed by Php-Server-Mon-Sys are available only to PHP Server Monitor; they are not intended to be available to other application software on the host system. The services are ephemeral; they come and go along with the installation, operation, and un-installation of Php-Server-Mon-Sys.
The Php-Server-Mon-Sys project is Open Source, and its public repository is located at:
The version of PHP Server Monitor incorporated into this release of Php-Server-Mon-Sys is PHP Server Monitor v3.1.1.
This version of Php-Server-Mon-Sys has been tested only on a host using Ubuntu 14.04. Php-Server-Mon-Sys has not yet been tested on OS X nor Windows. Theoretically, Php-Server-Mon-Sys should work on any host which fully supports Docker tools, but that has not yet been tested.
Installation and operation of Php-Server-Mon-Sys requires:
- Superuser access to a private host or VPS
- 300MB available memory
- 1.1GB available storage, (plus server history data accumulated in database)
- Internet connection/service
- Docker Engine 1.7, pre-installed
- Docker Compose 1.3.1, pre-installed
- Curl 7.35.0, pre-installed, (alternate equivalent may be substituted)
- UnZip 6.00, pre-installed, (alternate equivalent may be substituted)
- Tar (GNU tar) 1.27.1, pre-installed, (alternate equivalent may be substituted)
-
The following commands download the Php-Server-Mon-Sys release ZIP file, and unzip the contents into a newly created directory. Before entering the following commands, change the present working directory to where you want the Php-Server-Mon-Sys Home directory to be created. Then, enter the following commands:
$ curl -L -O https://github.com/addiscent/php-server-mon-sys/archive/master.zip $ unzip master.zip # create a new directory containing Php-Server-Mon-SysThe name of the new directory is php-server-mon-sys-master. The new directory is the Home directory for Php-Server-Mon-Sys. If you wish to rename the Php-Server-Mon-Sys Home directory, you may do so at any time. You may delete the master.zip file now, or later.
-
The following commands build Docker containers, and start Php-Server-Mon-Sys operation:
$ cd php-server-mon-sys-master # or to whatever you rename the directory $ ./build-psms.sh # execute this BASH script only in the "Home" directoryIMPORTANT: You must wait, (approximately two minutes), for MySQL to finish initializing its database before continuing with PHP Server Monitor Initialization instructions below. Otherwise, errors will be displayed during the PHP Server Monitor Initialization process. At this point, if an error is shown stating, "Unable to connect to MySQL. Please check your information", it is temporary. Wait a few minutes, and retry PHP Server Monitor Initialization.
Initially, you are evaluating the software. After you become familiar with it, you will probably decide to discard the first database created during PHP Server Monitor Initialization. However, before creating the database you plan to use "in production", read the three sections below titled:
-
Transitioning From Evaluation To Production
-
The PHP Server Monitor Database Passwords
-
The PHP Server Monitor Time Zone
-
After completing the Installation instructions above, use a web browser to visit:
-
Read and follow the directions on the first page, then choose LET'S GO.
-
Set your user, password, and email to whatever you wish, then choose INSTALL.
-
Read the page, follow the instructions, then choose GO TO YOUR MONITOR
-
Enter your user credentials and choose LOGIN. A page shows STATUS. The page is currently blank, because no servers have been chosen for monitoring.
-
Enter a server to monitor, and watch it, as described here:
-
Choose Servers from the menu at the top of the page. The next page shows Servers page.
-
Choose the green ADD NEW button. Enter the appropriate data into the fields, for a server you wish to monitor, then choose SAVE.
-
The Servers page refreshes, and now the server you entered on the previous page is in the list of servers to be monitored. Choose Status from the menu at the top of the page.
-
Notice a green box containing the name of the server you have chosen to be monitored. This page has several means of being refreshed to show the current status of the server. Let's use the manual update method now. Choose Update from the menu at the top of the page.
-
The contents of the green named-server box changes to "Last online: a second ago". Now, let's see a chart of the server's uptime history. Mouse-click on the green box containing your server's name.
-
A page titled Servers shows your server's profile information, and charts containing the access history of the chosen server. At this time, there is only one or a few points on the graph. Each point reflects the server's status at that time. The server's access history is updated in the database, a data point every three minutes, (default). However, the chart on this page does not automatically update, it must be refreshed manually, (using browser page refresh).
-
Let's change the configuration of PHP Server Monitor so that the main home page, Status, is automatically refreshed periodically, so you don't have to do it manually. Choose Config from the menu at the top of the page. A page titled Config is shown. In the field titled Auto-refresh, enter a time of 60 seconds, and choose Save. Now, choose Status from the menu at the top of the page.
-
Wait and watch for it, and notice that the contents of the green named-server box on the Status page is now auto-refreshed every 60 seconds. The Last online status should not show a value larger than 3 minutes unless the server is actually down, or whatever interval has been set for the server's update.
-
After ten or fifteen minutes have passed, mouse-click on the green box containing your server's name, and notice the chart now contains at least several data points of access history for your server, at the appropriate time interval.
-
-
See the PHP Server Monitor website and GitHub repository for documentation:
Php-Server-Mon-Sys-specific management commands, such as the .sh BASH scripts, and "docker-compose...", should always be executed with the Php-Server-Mon-Sys Home directory as the present working directory, (pwd).
The Php-Server-Mon-Sys system is managed using docker-compose commands:
* docker-compose up -d # loads and starts, or restarts, _Docker_ containers
* docker-compose stop # suspends container Operation
* docker-compose logs # shows a composite log generated by operating containers
* docker-compose rm # destroys loaded containers. "stop" them first.
The present working directory must be the Php-Server-Mon-Sys Home directory when entering these commands. Using these commands while the PWD is any other directory will show errors and the command scripts will fail.
Note that docker-compose rm is seldom used, typically only when completely uninstalling Php-Server-Mon-Sys.
See the Docker web site for related documentation:
The PHP Server Monitor database "persists" on the host file system, it is not ephemeral as are the Php-Server-Mon-Sys Docker service containers.
The Php-Server-Mon-Sys system, (technically, its Docker service containers), may be started, stopped, restarted, destroyed, and recreated without danger to the integrity of the PHP Server Monitor database, with one important caveat:
-
In order to prevent risk to the PHP Server Monitor database, the Php-Server-Mon-Sys Docker service containers must be created/stopped/destroyed using Docker commands, (docker-compose up, docker-compose stop, etc). Don't shutdown the host OS without first gracefully shutting down the Php-Server-Mon-Sys system, using the command:
$ docker-compose stopAfter re-booting the host OS, restart the Php-Server-Mon-Sys system by making the Php-Server-Mon-Sys home directory the present working directory, then enter the command:
$ docker-compose up -dAfter that command has reloaded the service containers, PHP Server Monitor will continue its job of monitoring services, and collecting and storing data in the PHP Server Monitor database.
When you have finished learning what Php-Server-Mon-Sys is all about, you will probably eventually wish to discard the data accumulated during evaluation. It may be very advantageous to perform this procedure at the same time you perform the procedures described in the sections below, The PHP Server Monitor Database Passwords and The PHP Server Monitor Time Zone.
Deleting the database causes Php-Server-Mon-Sys to automatically create a new one. Therefore, the easiest and fastest way to create an empty database, (discard the old data) is to simply delete the old one. Keep in mind that deleting the database deletes all data previously created during PHP Server Monitor Initialization. In addition to all server history data, the list of servers and any user and admin accounts are deleted.
To delete the existing database, enter the following commands:
$ sudo ./delete-database.sh # sudo or other superuser power required
$ docker-compose up -d # delete-database stops Php-Server-Mon-Sys, so re-start it
After the database is deleted, a new database will be automatically created when Php-Server-Mon-Sys is re-started. This will take several minutes, so wait a few. Then, use a web browser to visit your PHP Server Monitor page per usual, (default, localhost:28684). If you see an error message which says "can't connect to database", wait a little longer and retry. Follow the prompts and begin using as normal.
When Php-Server-Mon-Sys is installed, it automatically creates the database, (remember having to wait for two minutes?). The the database passwords are set to defaults at that time. If you wish to tighten up the security of your database, you may change the database passwords.
The database passwords cannot be changed by Php-Server-Mon-Sys after a database has been created; the passwords must be decided upon prior to creation of the database. A good time to do this is after you have finished evaluation of Php-Server-Mon-Sys and are ready to "go into production". At that time, you are most likely to decide you wish to abandon the first database and create a new one.
When you are ready to create a new database using new passwords, follow these steps:
-
Set new passwords into the appropriate configuration files by entering the following command:
$ ./set-passwords.sh root_password user_password # replace these passwords with your own
-
Re-build the PHP-FPM Docker container using the following command:
$ ./build-php-fpm.sh
-
Delete the database. The following commands stop Php-Server-Mon-Sys, delete the files containing the database, and then re-start Php-Server-Mon-Sys:
$ sudo ./delete-database.sh
$ docker-compose rm # obsolete PHP-FMP container must be unloaded
$ docker-compose up -d # re-start Php-Server-Mon-Sys. Loads re-built PHP-FPM container
It is necessary to wait for the database to finish initialization, (approximately two minutes).
The default PHP Server Monitor time zone is UTC. You may change the time zone by editing the php.ini file, located in the ./php-fpm/ sub-directory.
Note that the PHP Server Monitor Time Zone must only be changed BEFORE creating the PHP Server Monitor database. The PHP Server Monitor database is created during the process described above, in the section titled, PHP Server Monitor Initialization. If the PHP Server Monitor Time Zone setting after PHP Server Monitor Initialization, the timestamps on the data collected in the database will be out of sync with the displayed charts, rendering the collected data useless for charting in PHP Server Monitor.
To change the PHP Server Monitor Time Zone, search the ./php-fpm/php.ini file for the term date.timezone. Change the default value, UTC, to your time zone, e.g., America/Los_Angeles. For valid time zone codes, see:
http://www.php.net/manual/en/timezones.php
The default application service port number is 28684. You may change this port number by editing the docker-compose.yml file. Find the section which appears as follows:
ports:
- "28684:80"
Change the port number 28684 to any valid port number which does not conflict with other ports in use on the host. After editing this file, for any changes to take effect, Php-Server-Mon-Sys must be restarted, using the command:
$ docker-compose up -d
The interval at which monitored server histories are updated is determined by a PHP script which is executed periodically. The service which executes the script is Cron, an ubiquitous Linux service which is responsible for executing programs on a schedule. This task of executing a program periodically is known as a cron job. Cron jobs are specified by creating a file which contains one or more job descriptors. This type of file is known as a crontab, (Cron table), file.
In Php-Server-Mon-Sys, a cron job which updates server histories data is run on-board the PHP-FPM container. This cron job is started automatically when the Php-Server-Mon-Sys system is started, (using docker-compose up -d). The crontab file which contains the job descriptor needed by Cron is named etc-cron.d-tab-for-phpfpm.txt, (located in the home ./php-fpm/ sub-directory).
The interval specified in the crontab file determines how frequently the monitored servers are probed. The default interval is every 3 minutes. You may change the interval, by editing the crontab file. One way of editing the crontab file is by using the following command to open the file in an editor named nano:
$ nano ./php-fpm/etc-cron.d-tab-for-phpfpm.txt
The default job descriptor is:
*/3 * * * * root /usr/bin/php /var/www/public/cron/status.cron.php
Above, the "/3" after the asterisk tells Cron to execute the monitored servers' online history update every 3 minutes. You may change that number to, e.g., "/5" or "/15", or some other number of minutes, 2 through 59. If you want the history updated every minute, do not use "/1"; instead, use asterisk (*) by itself, that is, simply delete the "/3".
After editing the etc-cron.d-tab-for-phpfpm.txt file, the PHP-FPM Docker container image must be rebuilt, and then Php-Server-Mon-Sys restarted. Do so using the following commands:
$ ./build-php-fpm.sh # execute this from the PSMS Home directory
$ docker-compose up -d # restarts the Php-Server-Mon-Sys system
For more information about Cron, see:
https://en.wikipedia.org/wiki/Cron
The PHP Server Monitor database is a MySQL database. As such, it can be managed by using the appropriate MySQL-compatible software tools, such as a mysql client program, or phpMyAdmin. Though the PHP Server Monitor MySQL Docker container is local to the host, connections to the datbase server are made as if it is remote. Connections to remote MySQL servers are established using the server's IP address and a port number. The default port address is 3306. To discover the IP address of the server, use the following commands:
$ docker ps -a
result is similar to:
CONTAINER ID IMAGE ...etc
522b45f3c84f mysql:5.7.7 ...etc
Inspect the resulting list for a container whose IMAGE name is "mysql:...", and take note of its CONTAINER ID. To discover the IP address of that container, use the following command:
$ docker inspect -f "{{ .NetworkSettings.IPAddress }}" 522b45f3c84f # use your CONTAINER ID
result is similar to:
172.17.2.109
See instructions below for example client connections, using MySQL Client Program and phpMyAdmin.
The command below pulls and temporarily loads a mysql Docker container for use as a MySQL client. After exiting the mysql> prompt, the container is automatically discarded.
Enter the following command, (substitute the MySQL server Docker container IP address above as the IP address value):
$ docker run -it --rm mysql sh -c 'exec mysql -h"172.17.2.109" -P"3306" -uroot -p"mysecretpassword"'
result is similar to:
.
.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
mysql>
The text "mysql>" is a command prompt, waiting for you to enter MySQL commands:
mysql> show databases;
result:
+--------------------+
| Database |
+--------------------+
| information_schema |
| mysql |
| performance_schema |
| phpservermon |
| sys |
+--------------------+
5 rows in set (0.05 sec)
mysql> use phpservermon;
result:
Database changed
mysql> show tables;
result:
+------------------------+
| Tables_in_phpservermon |
+------------------------+
| psm_config |
| psm_log |
| psm_servers |
| psm_servers_history |
| psm_servers_uptime |
| psm_users |
| psm_users_preferences |
| psm_users_servers |
+------------------------+
8 rows in set (0.00 sec)
For more information about using the MySQL command line program, see:
http://dev.mysql.com/doc/refman/5.6/en/mysql.html
When ready to exit the mysql client, enter:
mysql> exit;
To connect phpMyAdmin to the PHP Server Monitor database server, the phpMyAdmin config.inc.php file must be revised, as follows.
Open the phpMyAdmin config.inc.php file in a text editor. Find the list of servers, which have entries similar to that given below, and add the following server code for the Php-Server-Mon-Sys MySQL server. Before inserting the code fragment given below, change the IP address from 172.17.2.109 to the address of the MySQL server Docker container discovered using the method described above. If you have previously changed your user or password for this database, also change those values in the code fragment below:
$i++;
$cfg['Servers'][$i]['verbose'] = 'Php-Server-Mon-Sys';
$cfg['Servers'][$i]['host'] = '172.17.2.109';
$cfg['Servers'][$i]['port'] = '3306';
$cfg['Servers'][$i]['socket'] = '';
$cfg['Servers'][$i]['connect_type'] = 'tcp';
$cfg['Servers'][$i]['auth_type'] = 'config';
$cfg['Servers'][$i]['user'] = 'phpservermon';
$cfg['Servers'][$i]['password'] = 'phpservermon';
IMPORTANT: Unfortunately, it is not uncommon for there to be more than one phpMyAdmin config.inc.php file on the host. If you edit one and it seems to have no affect, you may inadvertently be editing a copy of the file which is not the specific file used by phpMyAdmin. You may discover where copies are located using the following command:
$ sudo find / -maxdepth 4 -name config.inc.php
result, similar to this:
/usr/share/phpmyadmin/config.inc.php
/var/lib/phpmyadmin/config.inc.php
/etc/phpmyadmin/config.inc.php
For more information on editing the phpMyAdmin config.inc.php file, see:
http://docs.phpmyadmin.net/en/latest/config.html
Though unlikely to be necessary, you may make changes to the NGINX server configuration by editing the vhost.conf file, located in the home ./nginx/ sub-directory. After editing this file, for any changes to take effect, Php-Server-Mon-Sys must be restarted, using the command:
$ docker-compose up -d
Though unlikely to be necessary, you may make changes to the PHP-FPM server configuration by editing the php-fpm.conf and php.ini files, located in the ./php-fpm/ sub-directory. After editing these files, you must restart the Php-Server-Mon-Sys system as described above for any changes to take effect.
Several simple utility BASH scripts are available in the Php-Server-Mon-Sys home sub-directory. When using them, ensure they are invoked as BASH shell scripts typically are, e.g., ./build-psms.sh, (note the leading "./"). The scripts are safe to use only from within the Php-Server-Mon-Sys Home directory; when using them, be sure the present working directory is the Php-Server-Mon-Sys home sub-directory. If they are invoked outside this sub-directory, they will at best fail, or at worst possibly produce undesirable side effects.
-
dbash.sh - Executes a BASH shell on a running Docker container. To use it:
$ docker ps -a # shows a list of running containers. Note a CONTAINER ID...
result: CONTAINER ID IMAGE ... etc 7587be7d4eed nginx:1.9.2 ... etc$ ./dbash.sh 7587be7d4eed # execute a BASH shell on CONTAINER ID
result: root@7587be7d4eed:/#Where "root@7587be7d4eed:/#" indicates a prompt from within the running Docker container. The prompt is not running on a true terminal on-boad the container, so program screen output functionality is limited. However, it is useful enough for exploration inside the operating container, and troubleshooting if necessary. In the event you need to use, for example, a text viewer or editor, such as less or nano, set the TERM environment variable using the following command, (on the container, using the container's executing shell, not on the host):
$ export TERM=xterm -
build-php-fpm.sh - very seldom used. Prevents having to remember arcanum
The entire Php-Server-Mon-Sys Home directory, including the MySQL database, may be backed-up into a single .tar.gz file. To do so, use the provided BASH script command:
$ sudo ./backup-psms.sh # sudo or equivalent superpower is required
The backup script temporarily stops the operation of Php-Server-Mon-Sys, but operation is re-started automatically at the end of the backup operation. If a re-start is not desired, stop it manually using:
$ docker-compose stop
The backup file has a name similar to the following. The date and time of backup are added to filename during backup:
php-server-mon-sys.2015.0716.2256.tar.gz
To restore Php-Server-Mon-Sys from a back-up file created as described above, perform the following procedure:
-
Create a directory to be Php-Server-Mon-Sys Home. The name may be any you choose. As an example:
$ mkdir php-server-mon-sys # same as it ever was $ cd php-server-mon-sys -
Place the backup .tar.gz file here in the present working directory, (which is the new Php-Server-Mon-Sys Home). Use the following command to restore Php-Server-Mon-Sys, e.g.:
$ sudo tar -zxvf ./php-server-mon-sys.2015.0716.2256.tar.gzWhen tar execution is complete, the Php-Server-Mon-Sys Home directory contents is similar to:
drwxrwx--- 3 user group 4.0K Jul 16 13:26 mysql drwxrwx--- 2 user group 4.0K Jul 16 13:21 nginx . . -rw-rw-r-- 1 user group 12K Jul 4 01:24 LICENSE -rw-rw-r-- 1 user group 19K Jul 16 22:32 README.md -
To start Php-Server-Mon-Sys operation, enter the following commands:
$ ./build-psms.sh # build Docker container images $ docker-compose up -d # start operation
At this point, resuming use of Php-Server-Mon-Sys is very similar to the procedure described in the section above titled, PHP Server Monitor Initialization. Refer to that section. At one point a page is displayed which displays:
"We have discovered a previous version. In the next step we will upgrade your database to the latest version".
This is normal for a restored Php-Server-Mon-Sys system. Choose UPGRADE TO 3.1.1. Continue and LOG IN. The Php-Server-Mon-Sys continues normal operation per its configuration as when backed up.
To completely remove Php-Server-Mon-Sys, perform the following procedure:
-
Remove the running Docker containers:
$ docker-compose stop # gracefully shut down the Docker containers
$ docker-compose rm # unload the Docker containers
-
Delete the Php-Server-Mon-Sys home directory. Sudo or other superuser permissions are necessary to delete the MySQL database.
-
After deleting the home directory, you may remove the unnecessary Docker images from the local Docker image repository, in order to reclaim the storage space:
-
Discover the local Docker images using the command:
$ docker images
Their names are mysql, nginx, phusion/baseimage, raddiscentis/php-fpm, and temp/php-fpm-psm. Note their IMAGE IDs.
-
One by one, remove the images from the Docker image repository using the command:
$ docker rmi IMAGE ID.
-
If you inadvertently uninstall Php-Server-Mon-Sys without first using the docker-compose rm command, you may manually "clean up" the orphaned Docker containers by using Docker commands:
-
Discover the orphaned Docker containers by using the command:
$ docker ps -a # note the _CONTAINER IDs_ -
Remove the Docker containers by using the command:
$ docker rm -f <CONTAINER ID>
See the Docker documentation for details.
For questions and other support which are specific to PHP Server Monitor, please see PHP Server Monitor documentation and forum:
For general questions which are specific to Php-Server-Mon-Sys, (installation, configuration, container use/management, etc), you may send email to:
To request improved features, report bugs, or submit other software issues about Php-Server-Mon-Sys, please visit Php-Server-Mon-Sys project's Issues page on GitHub:
Licensed under Apache 2.0 License.
Copyright © 2015 Rex Addiscentis