Merge pull request #22 from ubellavance/master

Documentation improvement and many fixes/improvement to the code

README.md

@@ -1,59 +1,90 @@
-#Zend Server Puppet Module
-
-####Table of Contents
-
-1. [Overview](#Overview)
-2. [Module Description](#Module Description)
-3. [Setup](#Setup)
-    * [Components affected by this module](#Components affected by this module)
-    * [Setup requirements](#Setup requirements)
-    * [Getting started](#Getting Started)
-    * [Module Installation](#Module Installation)
-4. [Usage](#Usage)
-5. [Further Reference](#Further Reference)
-5. [Limitations](#Limitations)
-6. [Contributing to this module](#Contributing to this module)
-
-##Overview
+ Server Puppet Module
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Module Description](#module-description)
+3. [Setup](#setup)
+    * [Components affected by this module](#components-affected-by-this-module)
+    * [Setup requirements](#setup-requirements)
+    * [Getting started](#getting-started)
+    * [Module Installation](#module-installation)
+4. [Usage](#usage)
+5. [Further Reference](#further-reference)
+5. [Limitations](#limitations)
+6. [Contributing to this module](#contributing-to-this-module)
+
+## Overview
 The zendserver module allows you to easily manage Zend Server with Puppet.
 
-##Module Description
-This module installs, "bootstraps" and manages a cluster (or single machine) running Zend Server. Zend Server is an integrated PHP application server for mobile and web apps. Zend Server will also install a web server (apache/nginx) if it is not already installed on your system. Check http://www.zend.com for more information about Zend Server.
-
-##Setup
-
-###Components affected by this module
-The module downloads and installs:
-
- * Zend Server using the distro's package manager (apt/yum). 
- * Zend Framework (as a library in Zend Server)
- * Symphony php framework (as a library in Zend Server)
- * A web server (either apache or nginx) using the distro's package manager (apt/yum). 
- * Zend Server next generation SDK - (See https://github.com/zend-patterns/ZendServerSDK for details)
+## Module Description
+On the first run, this module:
+* Installs Zend Server
+* Installs the desired web server (httpd or nginx), if not already installed
+* Deploys an SDK client (zs-client.phar)
+  * Will be discontinued in the future as all supported Zend Server Versions already install it by default, in another location)
+  * The usage of `/usr/local/zend/bin/zs-client.sh` will probably replace the call to the phar
+* "bootstraps" the installation
+  * Deploys a file (`/usr/local/zend/bin/zs-puppet-common-functions.sh`), that contains functions for the bootstrap
+  * Sets the license
+  * Sets the admin and (optional) developer password for the web admin interface
+  * Creates a target
+    * A target is an API key/hash pair that is saved in a file, that allow one to do API calls using only the name of the target (does not send the key/hash pair on the network
+    * The target info (key/hash) is saved in a file, typically $home/.zsapi.ini. However, when using puppet,there is no $HOME, so the file is in /.zsapi.ini (at the root).  This may change in the future.
+* Configures  a cluster (or single machine) running Zend Server.
+  * Sets up a database for the cluster
+* Creates puppet facts about Zend Server
+  * The Zend Server-related facts are managed every puppet run
+
+It can also:
+
+* Define, deploy, remove or update an application
+* Deploy or remove a library
+* Install/enable/configure a 3rd-party extension (pear, pecl, OS package)
+* Do an API call with the SDK client
+  * See https://github.com/zend-patterns/ZendServerSDK for details
+* Execute commands with zs-manage (Using the SDK client should be preferred)
+* Create a target (most likely useless by itself, but used by the bootstrap process)
+
+Zend Server is an integrated PHP application server for mobile and web apps. Zend Server will also install a web server (apache/nginx) if it is not already installed on your system. Check http://www.zend.com for more information about Zend Server.
+
+## Setup
+
+### Components affected by this module
 
 The module modifies files under the following directories (and sub directories):
 
  * /usr/local/zend (and all sub-directories).
  * Apache configuration (/etc/apache2 or /etc/httpd depending on distro).
  * Nginx configuration (if relevant).
 
-###Setup Requirements
-Operating System:
+### Setup Requirements
+
+Typically, only vendor-supported (LTS, if applicable) versions are supported and tested with this module.
 
-* RHEL/Centos >=6
-* Debian >= 6
-* Ubuntu >= 10.04
+* Operating System. Currently vendor-supported version:
+
+  * [RHEL](https://access.redhat.com/support/policy/updates/errata/#Life_Cycle_Dates) 6+
+  * [Centos](https://wiki.centos.org/About/Product) 6+
+  * [Debian](https://wiki.debian.org/DebianReleases) 7+
+  * [Ubuntu](https://www.ubuntu.com/info/release-end-of-life) 12.04+
+
+* Zend Server
+Only the [currently supported Zend Server versions](http://www.zend.com/en/support-center/support/php-long-term-support) are supported and tested. Currently:
+  * 7.0
+  * 8.5
+  * 9.1
 
 Puppet dependencies:
 
  * Puppet version >= 3.4
  * The following puppet-forge modules:
     * puppetlabs/stdlibs
-    * puppetlabs/apt
+    * puppetlabs/apt (for Debian and Ubuntu)
 
-For a cluster environment also access to a mysql server.
+For a cluster environment, access to a mysql server is required.
 
-###Getting started
+### Getting started
 If you want to get started quickly you can checkout our [Vagrant testing box](https://github.com/davidl-zend/zendserverpuppet-vagrant). 
 
 This code will:
@@ -73,7 +104,7 @@ You can view and modify the following files to customize the vagrant setup:
  * /data/common.yaml  - This files contains parameters to be passed to puppet on the Vagrant box (using hiera).
  * /manifests/site.pp - Example puppet manifest which uses the zendserver module.
 
-###Module installation
+### Module installation
 
 To manually install the module:
 
@@ -97,29 +128,26 @@ To manually install the module:
 ```
 Alternatively you can use R10K to install the module and dependencies (see the puppet file in the above Vagrant test box for reference.
 
-##Usage
+## Usage
 For reference about the module's public API (classes and resources that should be used) check:
-[Module API reference](doc/API_REFERENCE.md)
+[Module API reference](doc/API_REFERENCE.md) or [SDK code on Github](https://github.com/zend-patterns/ZendServerSDK/). The [Zend Server documentation section about the API](http://files.zend.com/help/Zend-Server/content/introduction2.htm may also be useful).
 
 You can check the comments in the code for further information.
 
-##Further reference
+## Further reference
 You can check [Zend Server's online help zend-online-help](http://files.zend.com/help/Zend-Server/zend-server.htm) for instructions and more information.
 [R10K Instructions](http://terrarum.net/blog/puppet-infrastructure-with-r10k.html)
 
-##Limitations
+## Limitations
 The module is still under testing - please try it on a non-production system first.
 
   * It is recommended you do not use the module to manage a Zend Server system that was not installed with this module(Such a setup might work but is untested).
   * You should make sure that no other PHP installation is present on the system (such as the distros' php or manually installed versions).
-  * Before installing Zend Server, define the nginx repository: http://nginx.org/en/linux_packages.html#stable. (Without this installation of zend server will fail)
+  * Before installing Zend Server for use with Nginx, define the nginx repository: http://nginx.org/en/linux_packages.html#stable. (Without this installation of zend server will fail)
   * The module does not add /usr/local/zend/bin to the search path - you might want to do it yourself.
-  * Zend Server version >=7.0 (older versions are untested). Default version is 8.0.
-  * Support for apache (2.2/2.4) web server (nginx support is untested).
   * The module is not compatible with the puppetlabs/apache module. Do not use both modules to manage the same node (=server). puppetlabs/apache can be used to manage other nodes.
 
-##Contributing to this module
+## Contributing to this module
 If you wish to help our efforts you can open issues in the github repository or contribute code.
 To contribute, please fork the repository and send us a pull-request with your changes using github.
 You can email [email protected] for further questions.
-

manifests/bootstrap/exec.pp

@@ -15,8 +15,9 @@
     command => '/usr/local/zend/bin/zs-bootstrap-puppet.sh',
     creates => '/usr/local/zend/tmp/zs-done',
     require => [
+      Service ['zend-server'],    
       File['zs-bootstrap-puppet.sh'],
       File['/usr/local/zend/bin/zs-client.phar'],
       File['zs-puppet-common-functions.sh']],
   }
-}
+}

manifests/init.pp

@@ -5,11 +5,11 @@
 #[*accept_eula*]
 # Accept Zend Server End User License Agreement (default:true)
 #[*admin_password*]
-# Password for zend server console
+# Password for zend server web console/GUI (admin user)
 #[*manage_repos*]
 # Should the class manage Zend Server repositories (default:true)
 #[*webserver*]
-# Web Server to manage. Valid options:'apache','nginx' (default:'apache')
+# Web Server to install/manage. Valid options:'apache','nginx' (default:'apache')
 #[*phpversion*]
 # PHP version to install. (default:'5.5')
 #[*license_name*]
@@ -28,12 +28,25 @@
 # Password for Zend Server database.
 #[*db_schema*]
 # Schema to use for Zend Server (default:'zendserver')
+#[*db_host*]
+# Hostname of the MySQL server for ZS database
 #[*admin_api_key_name*]
-# Zend Server 64 charachter API key to use for interfacing with Zend Server (Default:'admin')
+# API key name to create (username part of the API key)
 #[*admin_api_key_secret*]
-#  = 'caff756fd7682fa35901afa923822f63771570c25afd5368eaa659f2f71d4d6f',
+# 64 character secret used to create an API key
+#[*admin_api_target_name*]
+# Name of the target to be used (must already exist, see SDK docs)
+#[*create_facts*]
+# Create facts or not (will send facts in the facter facts dir)
 #[*admin_email*]
 # Email address to which Zend Server will send administrative messages.
+#[*zsurl*]
+# Zend server API address (default = http://localhost:10081)
+#[*default_server*]
+# Default server
+#[*external_url*]
+# External URL
+
 # === Examples
 #
 # class {'zendserver':
@@ -75,7 +88,7 @@
   $db_host               = undef,
   $admin_api_key_name    = $zendserver::params::admin_api_key_name,
   $admin_api_key_secret  = $zendserver::params::admin_api_key_secret,
-  $admin_api_target_neme = $zendserver::params::admin_api_target_name,
+  $admin_api_target_name = $zendserver::params::admin_api_target_name,
   $create_facts          = $zendserver::params::create_facts,
   $admin_email           = $zendserver::params::admin_email,
   $zsurl                 = $zendserver::params::zsurl,
@@ -84,21 +97,24 @@
   validate_bool($manage_repos)
   validate_re($webserver, ['\Aapache|nginx\Z',], 'Only apache or nginx are supported.')
   validate_re($phpversion, ['\A5.3|5.4|5.5|5.6|7.0|7.1\Z',], 'Only versions 5.4 to 7.1 are supported.')
-  # TODO: api_key_name + web_api_key_secret are required if join_cluster=true
+  validate_re($admin_api_key_name, ['^\w{5,20}$','api_key_name is required and must be 5-20 characters.'])
+  validate_re($admin_api_key_secret, ['^\w{64}$','api_key_secret is required and must be 64 characters.'])
   anchor { 'zendserver::begin': } ->
-  class { '::zendserver::requirements': } ->
   class { '::zendserver::install': } ->
   class { '::zendserver::sdk::install': } ->
   class { '::zendserver::bootstrap': } ~>
   class { '::zendserver::cluster': } ~>
   class { '::zendserver::service': } ->
   anchor { 'zendserver::end': }
-  notify{ "zendserversetup key {$admin_api_key_name}": }
-  notify{ "zendserversetup secret {$admin_api_key_secret}": }
-  notify{ "zendserversetup hash ${zend_api_key_hash}":
-      require => [
-        Service['zend-server'],
-        Class['zendserver::bootstrap'],
-      ]
-  }
+
+# Removing all notifies because it makes unclean puppet runs
+# and it is useless as the api_key_name and secret is mandatory
+#  notify{ "zendserversetup key {$admin_api_key_name}": }
+#  notify{ "zendserversetup secret {$admin_api_key_secret}": }
+#  notify{ "zendserversetup hash ${zend_api_key_hash}":
+#      require => [
+#        Service['zend-server'],
+#        Class['zendserver::bootstrap'],
+#      ]
+#  }
 }

manifests/repo/debian.pp

@@ -22,7 +22,7 @@
 
   case $::operatingsystem {
     'Ubuntu' : {
-      if $::lsbdistrelease + 0 >= 14.04 {
+      if $::operatingsystemrelease + 0 >= 14.04 {
         $zend_repository = "http://repos.zend.com/zend-server/${zendserver::zend_server_version}/deb_apache2.4"
       } else {
         $zend_repository = "http://repos.zend.com/zend-server/${zendserver::zend_server_version}/deb_ssl1.0"

manifests/repo/redhat.pp

@@ -6,16 +6,27 @@
     warning("${name} should not be directly included in the manifest.")
   }
 
+ unless ($::osfamily == 'RedHat') and (versioncmp($::operatingsystemrelease, '6.0') >= 0) {
+    fail("OS family ${::osfamily}-${::operatingsystemrelease} is not supported. Only RedHat >= 6 is suppported. RHEL 5 is EOL")
+  }
+
+  $rpmdir = $::operatingsystemrelease ? {
+    /^5.*$/ => 'rpm',
+    /^6.*$/ => 'rpm',
+    /^7.*$/ => 'rpm_apache2.4',
+  }
+
+
   yumrepo { 'Zend':
-    baseurl  => "http://repos.zend.com/zend-server/${zendserver::zend_server_version}/rpm_apache2.4/${::architecture}",
+    baseurl  => "http://repos.zend.com/zend-server/${zendserver::zend_server_version}/${rpmdir}/${::architecture}",
     descr    => 'Zend Server',
     enabled  => 1,
     gpgcheck => 1,
     gpgkey   => 'http://repos.zend.com/zend.key',
   }
 
   yumrepo { 'Zend_noarch':
-    baseurl  => "http://repos.zend.com/zend-server/${zendserver::zend_server_version}/rpm_apache2.4/noarch",
+    baseurl  => "http://repos.zend.com/zend-server/${zendserver::zend_server_version}/${rpmdir}/noarch",
     descr    => 'Zend Server',
     enabled  => 1,
     gpgcheck => 1,