diff --git a/CHANGELOG b/CHANGELOG index 6182c0ec5..ad4db62ef 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,12 @@ +v4.3.2 Dec 28, 2015 +==================== + +* Add nginx 1.9.9, drop nginx 1.9.7 + (https://www.pivotaltracker.com/story/show/110627098) + +* Add httpd 2.4.18, drop httpd 2.4.17 + (https://www.pivotaltracker.com/story/show/110627098) + v4.3.1 Dec 09, 2015 ==================== diff --git a/README.md b/README.md index e5e4734cc..bf1ef6b73 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ ## Cloud Foundry PHP Buildpack -A buildpack for Cloud Foundry to deploy PHP based applications. +A buildpack to deploy PHP applications to Cloud Foundry based systems, such as a [public cloud provider](https://www.cloudfoundry.org/learn/providers/) or your own instance. ## 30 Second Tutorial -Getting started with the buildpack is easy. With the `cf` command line utility installed, open a shell, change directories to the root of your PHP files and push your application using the argument `-b https://github.com/cloudfoundry/php-buildpack.git`. +Getting started with this buildpack is easy. With the [`cf` command line utility](https://github.com/cloudfoundry/cli) installed, open a shell, change directories to the root of your PHP files and push your application using the argument `-b https://github.com/cloudfoundry/php-buildpack.git`. Example: @@ -20,24 +20,24 @@ EOF cf push -m 128M -b https://github.com/cloudfoundry/php-buildpack.git my-php-app ``` -Please note that you should change *my-php-app* to some unique name, otherwise you'll get an error and the push will fail. +Please note that you should change *my-php-app* to some unique name on your target Cloud Foundry instance, otherwise you'll get a hostname conflict error and the push will fail. -The example above will create and push a test application, "my-php-app", to Cloud Foundry. The `-b` argument instructs CF to use this buildpack. The remainder of the options and arguments are not specific to the buildpack, for questions on those consult the output of `cf help push`. +The example above will create and push a test application, *my-php-app*, to Cloud Foundry. The `-b` argument instructs CF to use this buildpack. The remainder of the options and arguments are not specific to the buildpack, for questions on those consult the output of `cf help push`. Here's a breakdown of what happens when you run the example above. - - On your PC... - - It'll create a new directory and one PHP file, which calls `phpinfo()` + - On your PC: + - It will create a new directory and one PHP file, which just invokes `phpinfo()` - Run `cf` to push your application. This will create a new application with a memory limit of 128M (more than enough here) and upload our test file. - - On Cloud Foundry... + - Within Cloud Foundry: - The buildpack is executed. - Application files are copied to the `htdocs` folder. - Apache HTTPD & PHP are downloaded, configured with the buildpack defaults and run. - - Your application is accessible at the URL `http://my-php-app.cfapps.io` (assuming your targeted towards Pivotal Web Services). + - Your application is accessible at the URL `http://my-php-app.example.com` (Replacing `example.com` with the domain of your public CF provider or private instance). ## More Information -While the *30 Second Tutorial* shows how quick and easy it is to get started using the buildpack, it skips over quite a bit of what you can do to adjust, configure and extend the buildpack. The following docs and links provide a more in-depth look at the buildpack. +While the *30 Second Tutorial* shows how quick and easy it is to get started using the buildpack, it skips over quite a bit of what you can do to adjust, configure and extend the buildpack. The following sections and links provide a more in-depth look at the buildpack. - [Supported Software](#supported-software) - [Features](#features) @@ -68,32 +68,33 @@ The [release notes page](https://github.com/cloudfoundry/php-buildpack/releases) ## Features -Here's a list of some special features of the buildpack. +Here are some special features of the buildpack. - - supports running commands or migration scripts prior to application startup - - supports an extension mechanism that allows the buildpack to provided additional functionality - - allows for application developers to provide custom extensions - - easy troubleshooting with the `BP_DEBUG` environment variable + - Supports running commands or migration scripts prior to application startup. + - Supports an extension mechanism that allows the buildpack to provide additional functionality. + - Allows for application developers to provide custom extensions. + - Easy troubleshooting with the `BP_DEBUG` environment variable. ## Examples Here are some example applications that can be used with this buildpack. - - [php-info] This app has a basic index page and shows the output of phpinfo() - - [PHPMyAdmin] A deployment of PHPMyAdmin that uses bound MySQL services - - [PHPPgAdmin] A deployment of PHPPgAdmin that uses bound Postgres services - - [Wordpress] A deployment of Wordpress that uses bound MySQL service - - [Drupal] A deployment of Drupal that uses bound MySQL service - - [CodeIgniter] CodeIgniter tutorial application running on CF - - [Stand Alone] An example which runs a stand alone PHP script - - [pgbouncer] An example which runs the pgbouncer process in the container to pool db connections. + - [php-info] This app has a basic index page and shows the output of `phpinfo()`. + - [PHPMyAdmin] A deployment of PHPMyAdmin that uses bound MySQL services. + - [PHPPgAdmin] A deployment of PHPPgAdmin that uses bound PostgreSQL services. + - [Wordpress] A deployment of WordPress that uses bound MySQL service. + - [Drupal] A deployment of Drupal that uses bound MySQL service. + - [CodeIgniter] CodeIgniter tutorial application running on CF. + - [Stand Alone] An example which runs a standalone PHP script. + - [pgbouncer] An example which runs the PgBouncer process in the container to pool database connections. - [phalcon] An example which runs a Phalcon based application. - [composer] An example which uses Composer. ## Getting Help -If you have questions, comments or need further help with the buildpack you can post to the [vcap-dev] mailing list. It's a good place for posting question on all of the open source Cloud Foundry components, like this buildpack. Alternatively, if you're using Pivotal Web Services with the buildpack, you could post to the [support forums]. +If you have questions, comments or need further help with the buildpack you can post to the [cf-dev](https://lists.cloudfoundry.org/archives/) mailing list. It's a good place for posting question on all of the open source Cloud Foundry components, like this buildpack. +If you are using one of the [many public CF providers](https://www.cloudfoundry.org/learn/providers/), please use their support channels. ## License The Cloud Foundry PHP Buildpack is released under version 2.0 of the [Apache License]. @@ -120,8 +121,8 @@ The Cloud Foundry PHP Buildpack is released under version 2.0 of the [Apache Lic 1. Use in Cloud Foundry - Upload the buildpack to your Cloud Foundry and optionally specify it by name - + Upload the buildpack to your Cloud Foundry instance and optionally specify it by name + ```bash cf create-buildpack custom_php_buildpack php_buildpack-cached-custom.zip 1 cf push my_app -b custom_php_buildpack @@ -164,7 +165,7 @@ Join the #buildpacks channel in our [Slack community] (http://slack.cloudfoundry ### Reporting Issues -This project is managed through Github. If you encounter any issues, bug or problems with the buildpack please open an issue. +This project is managed through GitHub. If you encounter any issues, bug or problems with the buildpack please open an issue. The project backlog is on [Pivotal Tracker](https://www.pivotaltracker.com/projects/1042066) diff --git a/VERSION b/VERSION index ecedc98d1..7e961f9e1 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -4.3.1 \ No newline at end of file +4.3.2 \ No newline at end of file diff --git a/defaults/options.json b/defaults/options.json index d3ba4d9e8..4d355cc23 100644 --- a/defaults/options.json +++ b/defaults/options.json @@ -5,7 +5,7 @@ "WEB_SERVER": "httpd", "PHP_VM": "php", "ADMIN_EMAIL": "admin@localhost", - "HTTPD_VERSION": "2.4.17", + "HTTPD_VERSION": "2.4.18", "HTTPD_PACKAGE": "httpd-{HTTPD_VERSION}.tar.gz", "HTTPD_DOWNLOAD_URL": "/httpd/{HTTPD_VERSION}/{HTTPD_PACKAGE}", "HTTPD_STRIP": true, @@ -13,7 +13,7 @@ "HTTPD_MODULES_STRIP": true, "NGINX_VERSION": "{NGINX_18_LATEST}", "NGINX_18_LATEST": "1.8.0", - "NGINX_19_LATEST": "1.9.7", + "NGINX_19_LATEST": "1.9.9", "NGINX_PACKAGE": "nginx-{NGINX_VERSION}.tar.gz", "NGINX_DOWNLOAD_URL": "/nginx/{NGINX_VERSION}/{NGINX_PACKAGE}", "NGINX_STRIP": true, diff --git a/docs/binaries.md b/docs/binaries.md index 910b58267..0fd20ec1c 100644 --- a/docs/binaries.md +++ b/docs/binaries.md @@ -1,22 +1,22 @@ ## Binaries -To reduce the time it takes for the build pack to run and setup a usable environment, the build pack makes use of precompiled binaries. For general use, these binaries are hosted on S3. If you're running on a public cloud like Pivotal Web Services, you should be able to use these binaries without any problems and you probably do not need to read any further. If you are running in a private environment or if for security reasons, you'd like to compile your own binaries, this document will explain what you need to do. +To reduce the time it takes for the buildpack to run and setup a usable environment, the buildpack makes use of precompiled binaries. For general use, these binaries are hosted on Amazon S3. If you're running on a public Cloud Foundry provider, you should be able to use these binaries without any problems and you probably do not need to read any further. If you are running in a private environment or if for security reasons you'd like to compile your own binaries, this document will explain what you need to do. -### Bundling Binaries With the Build Pack +### Bundling Binaries With the Buildpack -It is possible to bundle the required binaries with the build pack. When doing this, the build pack is self-contained and should have everything it needs to run. This is not possible if you're using a public CF instance that is run by someone else (i.e. Pivotal Web Services), however if you're running a private cloud then you can install the build pack (see `cf create-buildpack`), which is a nice option as the installed build pack is local and will not need to download anything from the internet. +It is possible to bundle the required binaries with the buildpack. When doing this, the buildpack is self-contained and should have everything it needs to run. This is not possible if you're using a public CF provider, but if you're running a private cloud then you can install the buildpack (see `cf create-buildpack`), which is a nice option as the installed buildpack is local and will not need to download anything from the Internet. Here are the steps you would need to do this. 1. Clone the repository. Check out a release branch, a specific commit or head. -1. Run `BUNDLE_GEMFILE=cf.Gemfile bundle exec buildpack-packager [ cached | uncached ]`. This will download the latest set of binaries and packagae it with the build pack that you have checked out. -1. Run `cf create-buildpack` pointing to the file that was generated in the previous step. This will install the build pack on your private cloud (as long as you have permissions). -1. Now you can `cf push` a PHP application and you no longer need to set the `-b` argument or specify the build pack in your manifest file. +1. Run `BUNDLE_GEMFILE=cf.Gemfile bundle exec buildpack-packager [ cached | uncached ]`. This will download the latest set of binaries and package it with the buildpack that you have checked out. +1. Run `cf create-buildpack` pointing to the file that was generated in the previous step. This will install the buildpack on your private cloud (as long as you have permissions). +1. Now you can `cf push` a PHP application and you no longer need to set the `-b` argument or specify the buildpack in your manifest file. -#### Use a Build Pack Bundle +#### Use a Buildpack Bundle -If you're running your own CF installation, like with PCF or Bosh Lite, you can follow these steps to install a bundled version of this build pack. +If you're running your own CF installation or BOSH Lite, you can follow these steps to install a bundled version of this buildpack. First, check if there is an existing `php_buildpack` already installed. @@ -49,7 +49,7 @@ python_buildpack 5 true false python_buildpack-offline-v1.0.1 php_buildpack 6 false false php_buildpack-offline-v1.0.1.zip ``` -Upload your bundled version of this build pack. +Upload your bundled version of this buildpack. ``` $ cf create-buildpack dm_php_buildpack php-build-pack-14.09.10-16.17.43.zip 7 --enable @@ -66,13 +66,13 @@ php_buildpack 6 false false php_buildpack-offline-v1.0.1. dm_php_buildpack 7 true false php-build-pack-14.09.10-16.17.43.zip ``` -Now to push an app using the build pack you installed. +Now to push an app using the buildpack you installed. - don't set the `-b` argument to cf push - remove `buildpack` from manifest.yml, if it exists - cf push -Alternatively, push and use the `-b` argument with the name of the build pack. From the example above, that's `dm_php_buildpack`. +Alternatively, push and use the `-b` argument with the name of the buildpack. From the example above, that's `dm_php_buildpack`. [PyEnv]:https://github.com/yyuu/pyenv diff --git a/docs/composer.md b/docs/composer.md index 103048019..bf97b5206 100644 --- a/docs/composer.md +++ b/docs/composer.md @@ -1,16 +1,16 @@ ## Composer -Yes!! We support [Composer]! +Yes! We support [Composer]! -Usage of the build pack with Composer is consistent to usage without it, so most of the standard documentation still applies. Where it does not, this document will fill in the Composer specific gaps. +Usage of the buildpack with Composer is consistent to usage without it, so most of the standard documentation still applies. Where it does not, this document will fill in the Composer specific gaps. 1. Usage of Composer requires a `composer.json` file. This should be placed in the root of your application. - 1. You are not required to push a `composer.lock` file with your application, although I would strongly encourage you to do so. It will ensure that a consistent set of dependencies are installed when you push to CloudFoundry. + 1. You are not required to push a `composer.lock` file with your application, although I would strongly encourage you to do so. It will ensure that a consistent set of dependencies are installed when you push to Cloud Foundry. - 1. You can require dependencies to packages and extensions. Extensions should be prefixed with the standard `ext-`. If you reference an extension that is available to the build pack, it will automatically be installed. See the main [README] for a list of supported extensions. + 1. You can require dependencies to packages and extensions. Extensions should be prefixed with the standard `ext-`. If you reference an extension that is available to the buildpack, it will automatically be installed. See the main [README] for a list of supported extensions. - 1. If you set the version of PHP to use in your `composer.json` (require -> php) or `composer.lock` (platform -> php) file, the build pack will take the version and install it. This will override the version information you set in the `options.json` file. + 1. If you set the version of PHP to use in your `composer.json` (require -> php) or `composer.lock` (platform -> php) file, the buildpack will take the version and install it. This will override the version information you set in the `options.json` file. The following format is supported for PHP version numbers. This is a small subset of the format supported by Composer. @@ -22,34 +22,34 @@ The following format is supported for PHP version numbers. This is a small subs ### Configuration -The build pack tries to run with a good set of default values for Composer. If you'd like to adjust things further, you can do so by adding a `.bp-config/options.json` file to your application and setting any of the following values in it. +The buildpack tries to run with a good set of default values for Composer. If you'd like to adjust things further, you can do so by adding a `.bp-config/options.json` file to your application and setting any of the following values in it. | Variable | Explanation | ------------------- | -----------------------------------------------------| | COMPOSER_VERSION | The version of Composer to use. It defaults to the latest. | -| COMPOSER_INSTALL_OPTIONS | A list of options that should be passed to `composer install`. This defaults to `--no-interaction --no-dev --no-progress`. The `--no-progress` option must be used due to the way the build pack calls Composer. | -| COMPOSER_VENDOR_DIR | Allows you to override the default value used by the build pack. This is passed through to Composer and instructs it where to create the `vendor` directory. Defaults to `{BUILD_DIR}/{LIBDIR}/vendor`. | -| COMPOSER_BIN_DIR | Allows you to override the default value used by the build pack. This is passed through to Composer and instructs it where to place executables from packages. Defaults to `{BUILD_DIR}/php/bin`. | -| COMPOSER_CACHE_DIR | Allows you to override the default value used by the build pack. This is passed through to Composer and instructs it where to place its cache files. Generally you should not change this value. The default is `{CACHE_DIR}/composer` which is a sub directory of the cache folder passed into the build pack (meaning that Composer cache files will be restored on subsequent application pushes. | +| COMPOSER_INSTALL_OPTIONS | A list of options that should be passed to `composer install`. This defaults to `--no-interaction --no-dev --no-progress`. The `--no-progress` option must be used due to the way the buildpack calls Composer. | +| COMPOSER_VENDOR_DIR | Allows you to override the default value used by the buildpack. This is passed through to Composer and instructs it where to create the `vendor` directory. Defaults to `{BUILD_DIR}/{LIBDIR}/vendor`. | +| COMPOSER_BIN_DIR | Allows you to override the default value used by the buildpack. This is passed through to Composer and instructs it where to place executables from packages. Defaults to `{BUILD_DIR}/php/bin`. | +| COMPOSER_CACHE_DIR | Allows you to override the default value used by the buildpack. This is passed through to Composer and instructs it where to place its cache files. Generally you should not change this value. The default is `{CACHE_DIR}/composer` which is a sub directory of the cache folder passed into the buildpack (meaning that Composer cache files will be restored on subsequent application pushes. | -### Github API Request Limits +### GitHub API Request Limits -Composer uses Github's API to retrive zip files for installation into the application folder. If you do not vendor dependencies before pushing an app, Composer will fetch dependencies at staging time using the Github API. +Composer uses GitHub's API to retrieve zip files for installation into the application folder. If you do not vendor dependencies before pushing an app, Composer will fetch dependencies at staging time using the GitHub API. -Github's API is request-limited. Once you have reached your hourly allowance of API requests (typically, 60), Github's API will begin to return 403 errors and staging will fail. +GitHub's API is request-limited. Once you have reached your hourly allowance of API requests (typically, 60), GitHub's API will begin to return 403 errors and staging will fail. To avoid this situation, there are two alternatives. -1. Vendor dependencies before pushing your application. -2. Supply a Github OAuth API token. +1. Vendor dependencies before pushing your application. +2. Supply a GitHub OAuth API token. #### Vendoring Dependencies To vendor dependencies, you will need to run `composer install` before you push your application. You may also need to configure `COMPOSER_VENDOR_DIR` to "vendor". -#### Supply a Github Token +#### Supply a GitHub Token -Composer can use [Github API OAuth tokens](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) to greatly increase your hourly request limit (typically to 5000). +Composer can use [GitHub API OAuth tokens](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) to greatly increase your hourly request limit (typically to 5000). During staging, the buildpack looks for this token in the environment variable `COMPOSER_GITHUB_OAUTH_TOKEN`. If you supply a valid token, Composer will use it during staging. This mechanism will not work if the token is invalid. diff --git a/docs/config.md b/docs/config.md index cbb81453a..b779cf441 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,36 +1,36 @@ ## Configuration -This build pack was built to be extremely flexible and configurable for an application developer. This document describes the different options that are available to an application developer and when he or she might want to use them. +This buildpack was built to be extremely flexible and configurable for the application developer. This document describes the different options that are available to an application developer and when he or she might want to use them. ### Defaults -The build pack stores all of its default configuration settings in the [defaults] directory. This is a good place to look if you want to see how something is configured out-of-the-box. +The buildpack stores all of its default configuration settings in the [defaults] directory. This is a good place to look if you want to see how something is configured out-of-the-box. ## options.json -The `options.json` file is the configuration file for the build pack itself. This instructs the build pack what to download, where to download it from and how to install it. Additionally it allows you to configure package names and versions (i.e. PHP, HTTPD or Nginx versions), the web server to use (HTTPD, Nginx or None) and the PHP extensions that are enabled. +The `options.json` file is the configuration file for the buildpack itself. This instructs the buildpack what to download, where to download it from and how to install it. Additionally it allows you to configure package names and versions (i.e. PHP, HTTPD or Nginx versions), the web server to use (HTTPD, Nginx or None) and the PHP extensions that are enabled. -To configure these options for your application, simply create the file `.bp-config/options.json` in your project directory. The build pack will find this file when it runs and merge it with the default values that it uses. Any values specified in your file will override the defaults. +To configure these options for your application, simply create the file `.bp-config/options.json` in your project directory. The buildpack will find this file when it runs and merge it with the default values that it uses. Any values specified in your file will override the defaults. Here are a list of the options that an application developer might want to override. | Variable | Explanation | ------------------- | -----------------------------------------------------| | WEB\_SERVER | Sets the web server to use. Should be one of 'httpd', 'nginx' or 'none'. This value defaults to 'httpd'. | -| HTTPD\_VERSION | Sets the version of Apache HTTPD to use. Currently the build pack supports the latest stable version. This value will default to the latest release that is supported by the build pack. | +| HTTPD\_VERSION | Sets the version of Apache HTTPD to use. Currently the buildpack supports the latest stable version. This value will default to the latest release that is supported by the buildpack. | | ADMIN\_EMAIL | The value used in HTTPD's configuration for [ServerAdmin] | -| NGINX\_VERSION | Sets the version of Nginx to use. Currently the build pack supports the latest stable version. This value will default to the latest release that is supported by the build pack. | -| PHP\_55\_LATEST | Set by the build pack, this provides the latest PHP 5.5.x release supported by the build pack. By setting PHP_VERSION to `{PHP_55_LATEST}`, your configuration will always use the latest PHP 5.5.x release. | -| PHP\_56\_LATEST | Set by the build pack, this provides the latest PHP 5.6.x release supported by the build pack. By setting PHP_VERSION to `{PHP_56_LATEST}`, your configuration will always use the latest PHP 5.6.x release. | +| NGINX\_VERSION | Sets the version of Nginx to use. Currently the buildpack supports the latest stable version. This value will default to the latest release that is supported by the buildpack. | +| PHP\_55\_LATEST | Set by the buildpack, this provides the latest PHP 5.5.x release supported by the buildpack. By setting PHP_VERSION to `{PHP_55_LATEST}`, your configuration will always use the latest PHP 5.5.x release. | +| PHP\_56\_LATEST | Set by the buildpack, this provides the latest PHP 5.6.x release supported by the buildpack. By setting PHP_VERSION to `{PHP_56_LATEST}`, your configuration will always use the latest PHP 5.6.x release. | | PHP\_VERSION | Sets the version of PHP to use. | | PHP\_EXTENSIONS | A list of the [extensions](#php-extensions) to enable. The default is to enable "bz2", "zlib", "curl" and "mcrypt". | -| PHP\_MODULES | A list of the [modules](#php-modules) to enable. The default is nothing. The build pack will automatically enable either the `fpm` or `cli` modules. If you want to force this, you can set this list to contain `fpm`, `cli`, `cgi` and / or `pear`. | +| PHP\_MODULES | A list of the [modules](#php-modules) to enable. The default is nothing. The buildpack will automatically enable either the `fpm` or `cli` modules. If you want to force this, you can set this list to contain `fpm`, `cli`, `cgi` and / or `pear`. | | ZEND\_EXTENSIONS | A list of the Zend extensions to enable. The defaut is not to enable any. | -| APP\_START\_CMD | This option is used to instruct the build pack what command to run if WEB_SERVER is set to `none` (i.e. it is a stand alone app). By default, the build pack will search for and run `app.php`, `main.php`, `run.php` or `start.php` (in that order). This option can be the name of the script to run or the name plus arguments. | +| APP\_START\_CMD | This option is used to instruct the buildpack what command to run if WEB_SERVER is set to `none` (i.e. it is a stand alone app). By default, the buildpack will search for and run `app.php`, `main.php`, `run.php` or `start.php` (in that order). This option can be the name of the script to run or the name plus arguments. | | WEBDIR | Set a custom location for your web or public files. This is the root directory from which the web server will host your files and the root directory from which PHP-FPM will look for your PHP files. Defaults to `htdocs`. Other common settings are `public`, `static` or `html`. Path is relative to `/home/vcap/app`. | -| LIBDIR | Set a custom library directory. This path is automatically added to the `include_path` by the build pack. Defaults to `lib`. Path is relative to `/home/vcap/app`. | -| HTTP\_PROXY | Instruct the build pack to use an HTTP proxy to download resources accessed via http. | -| HTTPS\_PROXY | Instruct the build pack to use an HTTP proxy to download resources accessed via https. | +| LIBDIR | Set a custom library directory. This path is automatically added to the `include_path` by the buildpack. Defaults to `lib`. Path is relative to `/home/vcap/app`. | +| HTTP\_PROXY | Instruct the buildpack to use an HTTP proxy to download resources accessed via http. | +| HTTPS\_PROXY | Instruct the buildpack to use an HTTP proxy to download resources accessed via https. | | ADDITIONAL\_PREPROCESS\_CMDS | A list of additional commands that should be run prior to the application. This allows developers a way to run things like migration scripts prior to the application being run. | For details about supported versions, please read the [release notes](https://github.com/cloudfoundry/php-buildpack/releases) for your buildpack version. @@ -39,7 +39,7 @@ For details about supported versions, please read the [release notes](https://gi ### HTTPD, Nginx and PHP configuration -The build pack will automatically configure HTTPD, Nginx and PHP for your application. In most situations this should just work, however if you need to adjust the configuration it can be done. +The buildpack will automatically configure HTTPD, Nginx and PHP for your application. In most situations this should just work, however if you need to adjust the configuration it can be done. The first step is to create a directory for the configuration files under the `.bp-config`. The new directory's name should be one or more of the following: `httpd`, `nginx` or `php`. Once created, simply add the configuration files to that directory. @@ -51,13 +51,13 @@ total 8 -rw-r--r-- 1 daniel staff 396 Jan 3 08:31 httpd-logging.conf ``` -In this example, we've created the `httpd` directory and added the `extra/httpd-logging.conf` file which matches the [extra/httpd-logging.conf] file is found in the build pack [defaults]. With this configuration file in place, the build pack will detect it and install it when the application is pushed to CF. +In this example, we've created the `httpd` directory and added the `extra/httpd-logging.conf` file which matches the [extra/httpd-logging.conf] file is found in the buildpack [defaults]. With this configuration file in place, the buildpack will detect it and install it when the application is pushed to CF. -By installing it, the build pack will override the default file of the same name. This means that the settings in the default file will no longer be applied, unless the application specific file also contains them as well. In fact, it's a good idea to take the default file from the build pack, use it as a starting point and edit as necessary. This will make it easier to edit the file without breaking the overall configuration. +By installing it, the buildpack will override the default file of the same name. This means that the settings in the default file will no longer be applied, unless the application specific file also contains them as well. In fact, it's a good idea to take the default file from the buildpack, use it as a starting point and edit as necessary. This will make it easier to edit the file without breaking the overall configuration. -A couple further notes. First, you are not limited to including configuration files that exist in the build pack default configuration. You can include files that only exist in the application, however the build pack will not know about these. Thus you'll need to adjust the configuration to take the new files into consideration. +A couple further notes. First, you are not limited to including configuration files that exist in the buildpack default configuration. You can include files that only exist in the application, however the buildpack will not know about these. Thus you'll need to adjust the configuration to take the new files into consideration. -Second, you need to take care when adjusting the configurations. It is possible for you to break the build pack's configuration and thus cause your application to fail. If you've included custom configuration, be sure to double check it if your application stops working. +Second, you need to take care when adjusting the configurations. It is possible for you to break the buildpack's configuration and thus cause your application to fail. If you've included custom configuration, be sure to double check it if your application stops working. ### PHP Extensions @@ -69,15 +69,15 @@ The PHP Buildpack also has support for using composer files within your PHP appl ### PHP Modules -In addition to extensions, there are a few PHP modules that can be installed. These are parts of the traditional PHP install that have been split out into their own download to decrease the size of the binaries used by the build pack by default. If you need one of these you can manually install the module by adding it to the `PHP_MODULES` list. +In addition to extensions, there are a few PHP modules that can be installed. These are parts of the traditional PHP install that have been split out into their own download to decrease the size of the binaries used by the buildpack by default. If you need one of these you can manually install the module by adding it to the `PHP_MODULES` list. The list of available modules includes `cli`, `fpm`, `cgi` and `pear`. The first one, `cli`, will install the `php` and `phar` binaries, the second, `fpm`, will install the PHP-FPM binary, the third, `cgi`, will install the `php-cgi` binary and the fourth, `pear`, will install PHP's Pear script and associated libraries. -In most cases, manually selecting one of these four special modules is not necessary. For example, the build pack will install the `cli` module when you push a stand alone application and it will install the `fpm` module when you run a web application. Currently the build pack will not install the `cgi` module or `pear`. If you need one of these, you'll have to instruct the build pack to install it. +In most cases, manually selecting one of these four special modules is not necessary. For example, the buildpack will install the `cli` module when you push a stand alone application and it will install the `fpm` module when you run a web application. Currently the buildpack will not install the `cgi` module or `pear`. If you need one of these, you'll have to instruct the buildpack to install it. ## Extensions -The behavior of the build pack can be controlled with extensions. Out-of-the-box the build pack includes some of it's own extensions like for [HTTPD], [Nginx], [PHP] and [NewRelic]. These are core extensions and will be automatically included by the build pack and used as necessary. In addition to these, it's possible for an application developer to include his or her own custom extensions. These should be placed into the `.extensions` directory of your project folder. When pushed, the build pack will look in this location for application specific extensions and run them. +The behavior of the buildpack can be controlled with extensions. Out-of-the-box the buildpack includes some of it's own extensions like for [HTTPD], [Nginx], [PHP] and [NewRelic]. These are core extensions and will be automatically included by the buildpack and used as necessary. In addition to these, it's possible for an application developer to include his or her own custom extensions. These should be placed into the `.extensions` directory of your project folder. When pushed, the buildpack will look in this location for application specific extensions and run them. The [Development Documentation] explains how to write extensions. diff --git a/docs/development.md b/docs/development.md index a52971aac..8926d7f60 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,13 +1,13 @@ ## Development -This doc aims to provide some help should you want to modify or extend the build pack. +This page aims to provide some help should you want to modify or extend the buildpack. ### Setup -To get setup developing the build pack, you'll need some tools. Here's the setup that should work. +To get setup developing the buildpack, you'll need some tools. Here's the setup that should work. 1. [PyEnv] - This will allow you to easily install Python 2.6.6, which is the same version available through the staging environment of CloudFoundry. - 1. [virtualenv] & [pip] - The build pack uses virtualenv and pip to setup the [required packages]. These are used by the unit test and not required by the build pack itself. + 1. [virtualenv] & [pip] - The buildpack uses virtualenv and pip to setup the [required packages]. These are used by the unit test and not required by the buildpack itself. With those tools installed, you should be able to run these commands to get up and running. @@ -31,30 +31,30 @@ The project is broken down into the following directories: - `docs` contains project documentation - `extensions` contains non-core extensions - `env` virtualenv environment - - `lib` contains core extensions, helper code and the build pack utils + - `lib` contains core extensions, helper code and the buildpack utils - `scripts` contains the Python scripts that run on compile, release and detect - `tests` contains test scripts and test data - `run_tests.sh` a convenience script for running the full suite of tests -### Understanding the Build Pack +### Understanding the Buildpack -The easiest way to understand the build pack is to trace the flow of the scripts. The build pack system calls the `compile`, `release` and `detect` scripts provided by the build pack. These are located under the `bin` directory and are generic. They simply redirect to the corresponding Python script under the `scripts` directory. +The easiest way to understand the buildpack is to trace the flow of the scripts. The buildpack system calls the `compile`, `release` and `detect` scripts provided by the buildpack. These are located under the `bin` directory and are generic. They simply redirect to the corresponding Python script under the `scripts` directory. -Of these, the `detect` and `release` scripts are straightforward, providing the minimal functionality required by a build pack. The `compile` script is more complicated but works like this. +Of these, the `detect` and `release` scripts are straightforward, providing the minimal functionality required by a buildpack. The `compile` script is more complicated but works like this. - load configuration - setup the `WEBDIR` directory - - install the build pack utils and the core extensions (HTTPD, Nginx & PHP) + - install the buildpack utils and the core extensions (HTTPD, Nginx & PHP) - install other extensions - install the `rewrite` and `start` scripts - setup the runtime environment and process manager - generate a startup.sh script -In general, you shouldn't need to modify the build pack itself. Instead creating an extension should be the way to go. +In general, you shouldn't need to modify the buildpack itself. Instead creating an extension should be the way to go. ### Extensions -The build pack heavily relies on extensions. An extensions is simply a set of Python methods that will get called at various times during the staging process. +The buildpack relies heavily on extensions. An extension is simply a set of Python methods that will get called at various times during the staging process. #### Creation @@ -69,11 +69,11 @@ def configure(ctx): pass ``` -The `configure` method gives extension authors a chance to adjust the configuration of the build pack prior to *any* extensions running. The method is called very early on in the lifecycle of the build pack, so keep this in mind when using this method. The purpose of this method is to allow an extension author the opportunity to modify the configuration for PHP, the Web Server or another extension prior to those compoents being installed. +The `configure` method gives extension authors a chance to adjust the configuration of the buildpack prior to *any* extensions running. The method is called very early on in the lifecycle of the buildpack, so keep this in mind when using this method. The purpose of this method is to allow an extension author the opportunity to modify the configuration for PHP, the web server or another extension prior to those components being installed. An example of when to use this method would be to adjust the list of PHP extensions that are going to be installed. -The method takes one argument, which is the build pack context. You can edit the context to update the state of the build pack. Return value is ignore / not necessary. +The method takes one argument, which is the buildpack context. You can edit the context to update the state of the buildpack. Return value is ignore / not necessary. ```python @@ -92,7 +92,7 @@ def service_commands(ctx): return {} ``` -The `service_commands` method gives extension authors the ability to contribute a set of services that need to be run. These commands are run and should continue to run. If any service exits, the process manager will halt all of the other services and the application will be restarted by CloudFoundry. +The `service_commands` method gives extension authors the ability to contribute a set of services that need to be run. These commands are run and should continue to run. If any service exits, the process manager will halt all of the other services and the application will be restarted by Cloud Foundry. The method takes the context as an argument and should return a dictionary of services to run. The key should be the service name and the value should be a tuple which is the command and arguments. @@ -103,26 +103,26 @@ def service_environment(ctx): The `service_environment` method gives extension authors the ability to contribute environment variables that will be set and available to the services. -The method takes the build pack context as its argument and should return a dictionary of the environment variables to be added to the environment where services (see `service_commands`) are executed. +The method takes the buildpack context as its argument and should return a dictionary of the environment variables to be added to the environment where services (see `service_commands`) are executed. The key should be the variable name and the value should be the value. The value can either be a string, in which case the environment variable will be set with the value of the string or it can be a list. If it's a list, the contents will be combined into a string and separated by the path separation character (i.e. ':' on Unix / Linux or ';' on Windows). Keys that are set multiple times by the same or different extensions are automatically combined into one environment variable using the same path separation character. This is helpful when two extensions both want to contribute to the same variable, for example LD_LIBRARY_PATH. -Please note that environment variables are not evaluated as they are set. This would not work because they are set in the staging environment which is different than the execution environment. This means you cannot do things like `PATH=$PATH:/new/path` or `NEWPATH=$HOME/some/path`. To work around this, the build pack will rewrite the environment variable file before it's processed. This process will replace any `@` markers with the value of the environment variable from the execution environment. Thus if you do `PATH=@PATH:/new/path` or `NEWPATH=@HOME/some/path`, the service end up with a correctly set `PATH` or `NEWPATH`. +Please note that environment variables are not evaluated as they are set. This would not work because they are set in the staging environment which is different than the execution environment. This means you cannot do things like `PATH=$PATH:/new/path` or `NEWPATH=$HOME/some/path`. To work around this, the buildpack will rewrite the environment variable file before it's processed. This process will replace any `@` markers with the value of the environment variable from the execution environment. Thus if you do `PATH=@PATH:/new/path` or `NEWPATH=@HOME/some/path`, the service end up with a correctly set `PATH` or `NEWPATH`. ```python def compile(install): return 0 ``` -The `compile` method is the main method and where extension authors should perform the bulk of their logic. This method is called by the build pack while it's installing extensions. +The `compile` method is the main method and where extension authors should perform the bulk of their logic. This method is called by the buildpack while it's installing extensions. The method is given one argument which is an Installer builder object. The object can be used to install packages, configuration files or access the context (for examples of all this, see the core extensions like [HTTPD], [Nginx], [PHP] and [NewRelic]). The method should return 0 when successful or any other number when it fails. Optionally, the extension can raise an exception. This will also signal a failure and it can provide more details about why something failed. ##### Method Order -It is sometimes useful to know what order the build pack will use to call the methods in an extension. They are called in the following order. +It is sometimes useful to know what order the buildpack will use to call the methods in an extension. They are called in the following order. 1. `configure` 2. `compile` @@ -172,16 +172,16 @@ def compile(install): #### Tips - - To be consistent with the rest of the build pack, extensions should import and use the standard logging module. This will allow extension output to be incorporated into the output for the rest of the build pack. - - The build pack will run every extension that is included with the build pack and the application. There is no mechanism to disable specific extensions. Thus, when you write an extension, you should make some way for the user to enable / disable it's functionality. See the [NewRelic] extension for an example of this. - - If an extension requires configuration, it should be included with the extension. The `defaults/options.json` file is for the build pack and its core extensions. See the [NewRelic] build pack for an example of this. + - To be consistent with the rest of the buildpack, extensions should import and use the standard logging module. This will allow extension output to be incorporated into the output for the rest of the buildpack. + - The buildpack will run every extension that is included with the buildpack and the application. There is no mechanism to disable specific extensions. Thus, when you write an extension, you should make some way for the user to enable / disable it's functionality. See the [NewRelic] extension for an example of this. + - If an extension requires configuration, it should be included with the extension. The `defaults/options.json` file is for the buildpack and its core extensions. See the [NewRelic] buildpack for an example of this. - Extensions should have their own test module. This generally takes the form `tests/test_.py`. ### Testing #### Running unit tests -The build pack makes use of [Nose] for testing. You can run the full suite of tests with this command. +The buildpack makes use of [Nose] for testing. You can run the full suite of tests with this command. ``` ./run_tests.sh @@ -214,4 +214,3 @@ Data for all tests is stored under `tests/data`. [PHP]:https://github.com/cloudfoundry/php-buildpack/tree/master/lib/php [NewRelic]:https://github.com/cloudfoundry/php-buildpack/tree/master/extensions/newrelic [unit tests]:https://github.com/cloudfoundry/php-buildpack/blob/master/docs/development.md#testing - diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 4a6693223..8f4f3c54b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,22 +1,22 @@ ## Troubleshooting -The build pack should work in most situations, although nothings perfect so you may need to debug it. There are a couple easy ways to debug the build pack. +The buildpack should work in most situations. If not, there are a couple easy ways to diagnose problems. - 1. Check the output from the build pack. It writes some basic information to stdout, like the files that are being downloaded. Additionally, it will write more information should something fail, specifically you'll see a stack trace explaining why. + 1. Check the output from the buildpack. It writes some basic information to stdout, like the files that are being downloaded. Additionally, it will write more information should something fail, specifically you'll see a stack trace explaining why. - 1. Check the logs from the build pack. The build pack writes logs to disk and you can retrieve them with the `cf files` command. + 2. Check the logs from the buildpack. The buildpack writes logs to disk and you can retrieve them with the `cf files` command. - ``` + ```bash cf files app/.bp/logs/bp.log ``` - The output from this log is a little more detailed than what is written to stdout, but does skip some information which might be helpful to understand the state of the build pack when it fails. - + The output from this log is a little more detailed than what is written to stdout, but does skip some information which might be helpful to understand the state of the buildpack when it fails. + ### Enable Debug Mode -To get the most information from the build pack, you can put it into debug mode. To do this, simply set the `BP_DEBUG` environment variable to `true` (or anything really, it just needs to be set). This will instruct the build pack to set it's log level to DEBUG and it'll write to stdout. The combination of these two should provide quite a bit of detail about the state of the build pack as it runs. +To get the most information from the buildpack, you can put it into debug mode. To do this, simply set the `BP_DEBUG` environment variable to `true` (or anything really, it just needs to be set). This will instruct the buildpack to set it's log level to DEBUG and it'll write to stdout. The combination of these two should provide quite a bit of detail about the state of the buildpack as it runs. -``` +```bash cf se BP_DEBUG true ``` diff --git a/docs/usage.md b/docs/usage.md index ead9ab2d3..c93c97758 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,14 +1,14 @@ # Usage -Getting started with the build pack is simple. It's designed to be easy to use and minimally invasive. For a quick start, see the [30 Second Tutorial]. This document will go into further detail and explain the more advanced options. +Getting started with the buildpack is simple. It's designed to be easy to use and minimally invasive. For a quick start, see the [30 Second Tutorial]. This document will go into further detail and explain the more advanced options. ## Folder Structure -The easiest way to use the build pack is to put your assets and PHP files into a directory and push it to CloudFoundry. When you do this, the build pack will take your files and automatically move them into the `WEBDIR` (defaults to `htdocs`) folder, which is the directory where your chosen web server looks for the files. +The easiest way to use the buildpack is to put your assets and PHP files into a directory and push it to Cloud Foundry. When you do this, the buildpack will take your files and automatically move them into the `WEBDIR` (defaults to `htdocs`) folder, which is the directory where your chosen web server looks for the files. ### URL Rewriting -If you select Apache as your webserver, you can include `.htaccess` files with your application. +If you select Apache as your web server, you can include `.htaccess` files with your application. Alternatively, you can [provide your own Apache or Nginx configurations]. @@ -30,7 +30,7 @@ total 0 -rw-r--r-- 1 daniel staff 0B Feb 27 21:40 my.class.php <-- not public, http://app.cfapps.io/lib/my.class.php == 404 ``` -This comes with a catch. If your project legitimately has a `lib` directory, these files will not be publicly available because the build pack does not copy a top-level `lib` directory into the `WEBDIR` folder. If your project has a `lib` directory that needs to be publicly available then you have two options. +This comes with a catch. If your project legitimately has a `lib` directory, these files will not be publicly available because the buildpack does not copy a top-level `lib` directory into the `WEBDIR` folder. If your project has a `lib` directory that needs to be publicly available then you have two options. #### Option #1 @@ -85,11 +85,11 @@ The second option is to pick a different name for the `LIBDIR`. This is a confi #### Other Folders -Beyond the `WEBDIR` and `LIBDIR` directories, the build pack also supports a `.bp-config` directory and a `.extensions` directory. +Beyond the `WEBDIR` and `LIBDIR` directories, the buildpack also supports a `.bp-config` directory and a `.extensions` directory. -The `.bp-config` directory should exist at the root of your project directory and it is the location of application specific configuration files. Application specific configuration files override the default settings used by the build pack. This link explains [application configuration files] in depth. +The `.bp-config` directory should exist at the root of your project directory and it is the location of application specific configuration files. Application specific configuration files override the default settings used by the buildpack. This link explains [application configuration files] in depth. -The `.extensions` directory should also exist at the root of your project directory and it is the location of application specific custom extensions. Application specific custom extensions allow you, the developer, to override or enhance the behavior of the build pack. This link explains [extensions] in more detail. +The `.extensions` directory should also exist at the root of your project directory and it is the location of application specific custom extensions. Application specific custom extensions allow you, the developer, to override or enhance the behavior of the buildpack. This link explains [extensions] in more detail. [30 Second Tutorial]:https://github.com/cloudfoundry/php-buildpack#30-second-tutorial [application configuration files]:https://github.com/cloudfoundry/php-buildpack/blob/master/docs/config.md diff --git a/manifest.yml b/manifest.yml index 7d7e5157a..d83ff85ee 100644 --- a/manifest.yml +++ b/manifest.yml @@ -33,11 +33,11 @@ dependencies: - cflinuxfs2 md5: 069eb3a0a3522a6461c011bcd98f99a6 - name: httpd - version: 2.4.17 - uri: https://pivotal-buildpacks.s3.amazonaws.com/concourse-binaries/httpd/httpd-2.4.17-linux-x64.tgz + version: 2.4.18 + uri: https://pivotal-buildpacks.s3.amazonaws.com/concourse-binaries/httpd/httpd-2.4.18-linux-x64.tgz cf_stacks: - cflinuxfs2 - md5: 455c7205911b5a7db0a263eee97b15a3 + md5: 5f48cda4ba1ffa954c4d1f71b51ccf7e - name: php version: 5.5.29 uri: https://pivotal-buildpacks.s3.amazonaws.com/concourse-binaries/php/php-5.5.29-linux-x64-1442441030.tgz @@ -73,11 +73,11 @@ dependencies: - cflinuxfs2 md5: e12cddcba72d5008f94b298a02a8e6d4 - name: nginx - version: 1.9.7 - uri: https://pivotal-buildpacks.s3.amazonaws.com/concourse-binaries/nginx/nginx-1.9.7-linux-x64.tgz + version: 1.9.9 + uri: https://pivotal-buildpacks.s3.amazonaws.com/concourse-binaries/nginx/nginx-1.9.9-linux-x64.tgz cf_stacks: - cflinuxfs2 - md5: 3d57867198dad5aa1fa87ec8f969eafa + md5: b3726a282725dd999470f0dfd4b838c4 - name: composer version: 1.0.0-alpha10 uri: https://pivotal-buildpacks.s3.amazonaws.com/php/binaries/trusty/composer/1.0.0-alpha10/composer.phar