Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #763 from WalkerWatch/docupdates/chapter17 

Chapter 17 cleanup.
This commit is contained in:
Jesse McConnell 2016-07-26 07:51:38 -05:00 committed by GitHub
parent aa86d120e5 e368f3d8ee
commit 043b494c57
2 changed files with 37 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
jetty-documentation/src/main/asciidoc/administration/fastcgi/configuring-fastcgi.adoc
View File

@ -19,12 +19,12 @@
In this section you will see how to configure Jetty to serve WordPress via FastCGI.
The first step is to have WordPress installed in your server machine, for example under `/var/www/wordpress`.
The first step is to have WordPress installed on your server machine, for example under `/var/www/wordpress`.
For more information about how to install WordPress, please refer to the https://codex.wordpress.org/Installing_WordPress[WordPress Installation Guide].
The second step is to install `php-fpm` and make sure it is configured to listen on a TCP socket; typically it is configured to listen to `localhost:9000`.
The third step is to install Jetty, for example under `/opt/jetty`, called in the following `$JETTY_HOME`.
The third step is to install Jetty, for example under `/opt/jetty`, called in the following `$JETTY_HOME`.
Refer to xref:jetty-downloading[] for more information about how to install Jetty.
The fourth step is to create a Jetty base directory (see xref:startup-base-and-home[]), called in the following `$JETTY_BASE`, where you setup the configuration needed to support FastCGI in Jetty, and configure the `fcgi`, `http` and `deploy` modules, so that Jetty will be able to accept HTTP requests from browsers, convert them in FastCGI, and proxy them to `php-fpm`:
@ -33,16 +33,16 @@ The fourth step is to create a Jetty base directory (see xref:startup-base-and-h
....
$ mkdir -p /usr/jetty/wordpress
$ cd /usr/jetty/wordpress
$ java -jar $JETTY_HOME/start.jar --add-to-module=fcgi,http,deploy
$ java -jar $JETTY_HOME/start.jar --add-to-startd=fcgi,http,deploy
....
Therefore `$JETTY_BASE=/usr/jetty/wordpress`.
The fifth step is to deploy the web application that provides the proxying of client requests to the FastCGI server, `php-fpm`.
Typically this is done by deploying a `*.war` file in the `$JETTY_BASE/webapps` directory, but in case of FastCGI there is really nothing of this web application that you have to write: all the work is already done for you by the Jetty developers.
Therefore you just need to deploy a Jetty XML file that configures the web application directly.
Copy and paste the following content as `$JETTY_BASE/webapps/jetty-wordpress.xml`
The fifth step is to deploy the web application that provides the proxying of client requests to the FastCGI server, `php-fpm`.
Typically this is done by deploying a `*.war` file in the `$JETTY_BASE/webapps` directory.
For FastCGI there is no web application that needs developed - all the work has already been done for you by Jetty.
As such you only need to deploy a Jetty context XML file that configures the web application directly.
Copy and paste the following content as `$JETTY_BASE/webapps/jetty-wordpress.xml`:
[source, xml, subs="{sub-order}"]
----
@ -114,32 +114,32 @@ Copy and paste the following content as `$JETTY_BASE/webapps/jetty-wordpress.xml
</Call>
</Configure>
----
Explanation of this file content:
An explanation of the above contents:
* At line 6 it is specified the WordPress installation directory, in this example `/var/www/wordpress` (as defined in the first step).
* At line 9 it is specified the context path at which WordPress will be served, in this example at the root context path `/`.
* At line 10 it is specified the resource base of the context, also set to the WordPress installation directory. This allows Jetty to serve static resources directly from the WordPress installation directory.
* At line 12 it is specified the welcome file as `index.php`, so that Jetty can perform the proper redirects in case of URIs ending with the `/` character.
* At line 15 it is specified the `TryFilesFilter`, a Servlet Filter that has been inspired by the http://wiki.nginx.org/HttpCoreModule#try_files[try_files] functionality offered by Nginx.
This filter tries to serve the resource from the file system first, and if the resource is not found it forwards the request as `index.php?p=$path`, which will match the proxy servlet defined below.
* Linne 6 specifies the WordPress installation directory, in this example `/var/www/wordpress` (as defined in the first step).
* Line 9 it is specified the context path at which WordPress will be served, in this example at the root context path `/`.
* Line 10 specifies the resource base of the context, also set to the WordPress installation directory.
This allows Jetty to serve static resources directly from the WordPress installation directory.
* Line 12 specifies the welcome file as `index.php`, so that Jetty can perform the proper redirects in case of URIs ending with the `/` character.
* Line 15 specifies the `TryFilesFilter`, a Servlet Filter that has been inspired by the http://wiki.nginx.org/HttpCoreModule#try_files[try_files] functionality offered by Nginx.
This filter tries to serve the resource from the file system first, and if the resource is not found it forwards the request as `index.php?p=$path`, which will match the proxy servlet defined below.
Refer to the link:{JDURL}/org/eclipse/jetty/fcgi/server/proxy/TryFilesFilter.html[TryFilesFilter] documentation for further information.
* At line 29 it is specified Jetty's `DefaultServlet` to serve static content such as CSS files, JavaScript files, etc. `DefaultServlet` will serve these files by looking in the resource base of the context, defined at line 10 (see above).
* At line 47 it is specified the `FastCGIProxyServlet`, a Servlet that proxies HTTP requests arriving from clients to FastCGI requests to the FastCGI server.
* At line 52 it is specified the TCP address of the FastCGI server (`php-fpm`), where HTTP requests are forwarded as FastCGI requests.
* At line 60 it is specified once again the WordPress installation directory, so that the `FastCGIProxyServlet` can pass this information to the FastCGI server.
* At line 64 it is specified a regular expression that matches request URIs performed to this servlet, in addition to the standard URL mapping defined by Servlet at line 49.
* Line 29specifies Jetty's `DefaultServlet` to serve static content such as CSS files, JavaScript files, etc. `DefaultServlet` will serve these files by looking in the resource base of the context, defined at line 10 (see above).
* Line 47 specifies the `FastCGIProxyServlet`, a Servlet that proxies HTTP requests arriving from clients to FastCGI requests to the FastCGI server.
* Line 52 specifies the TCP address of the FastCGI server (`php-fpm`), where HTTP requests are forwarded as FastCGI requests.
* Line 60 specifies once again the WordPress installation directory, so that the `FastCGIProxyServlet` can pass this information to the FastCGI server.
* Line 64 specifies a regular expression that matches request URIs performed to this servlet, in addition to the standard URL mapping defined by Servlet at line 49.
Refer to the link:{JDURL}/org/eclipse/jetty/fcgi/server/proxy/FastCGIProxyServlet.html[FastCGIProxyServlet] documentation for further information.
The last step is to start Jetty (see xref:startup[]) and hit `http://localhost:8080` with your browser and enjoy WordPress:
The last step is to start Jetty (see xref:startup[]) and navigate to `http://localhost:8080` with your browser and enjoy WordPress:
[source, screen, subs="{sub-order}"]
....
$ cd $JETTY_BASE
$ java -jar /opt/jetty/start.jar
....
[[configuring-fastcgi-http2]]
@ -147,25 +147,24 @@ $ java -jar /opt/jetty/start.jar
In order to configure Jetty to listen for HTTP/2 requests from clients that are HTTP/2 enabled and forward them to the FastCGI server as FastCGI requests, you need to enable the `http2` module, which in turn will require a TLS connector and consequently a keystore to read the key material required by TLS.
Enabling the `http2` is really simple; in additions to the modules you have enabled above, add the `http2` module:
Enabling the `http2` is easy; in additions to the modules you have enabled above, add the `http2` module:
[source, screen, subs="{sub-order}"]
....
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2
$ java -jar $JETTY_HOME/start.jar --add-to-startd=http2
....
The command above adds the `http2` module (and its dependencies) to the existing modules and uses the default Jetty keystore to provide the key material required by TLS.
The command above adds the `http2` module (and its dependencies) to the existing modules and uses the default Jetty keystore to provide the key material required by TLS.
You will want to use your own keystore with your own private key and certificate for your own domain.
Remember that by adding the `http2` module, you will start two JVMs: one that reads the configuration, and one that has the ALPN boot boot jar in the boot classpath, as explained in xref:http2-configuring[].
Since now your site will run over TLS, you need to make sure that the WordPress URL is also configured so.
If you have followed the steps of the link:#configuring-fastcgi[previous section], your WordPress site is served at `http://localhost:8080`.
Since now your site will run over TLS, you need to make sure that the WordPress URL is also configured so.
If you have followed the steps of the link:#configuring-fastcgi[previous section], your WordPress site is served at `http://localhost:8080`.
You will need to change that to be `https://localhost:8443` from the WordPress administration web interface, or follow the http://codex.wordpress.org/Changing_The_Site_URL[WordPress instructions] to do so without using the administration web interface.
The minimal modules required to run WordPress with Jetty on HTTP/2 are therefore: `http2`, `http`, `fcgi` and `deploy`.
The minimal modules required to run WordPress with Jetty on HTTP/2 are therefore: `http2`, `http`, `fcgi` and `deploy`.
These will setup a clear text connector on port 8080 for HTTP/1.1 and a TLS connector on port 8443 for HTTP/2 and HTTP/1.1.
At this point, you can start Jetty (see xref:startup[]), hit `http://localhost:8080` with your browser and enjoy WordPress via HTTP/2 using a HTTP/2 enabled browser:
@ -174,7 +173,6 @@ At this point, you can start Jetty (see xref:startup[]), hit `http://localhost:8
....
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar
....
If you don't have a HTTP/2 enabled browser, WordPress will still be available over plain HTTP/1.1.
If you don't have a HTTP/2 enabled browser, WordPress will still be available over HTTP/1.1.

14
jetty-documentation/src/main/asciidoc/administration/fastcgi/fastcgi-intro.adoc
View File

@ -17,18 +17,18 @@
[[fastcgi-intro]]
=== FastCGI Introduction
FastCGI is a network protocol primarily used by a _web server_ to communicate to a __FastCGI server__.
FastCGI is a network protocol primarily used by a _web server_ to communicate to a __FastCGI server__.
FastCGI servers are typically used to serve web content generated by dynamic web languages, primarily http://www.php.net/[PHP], but also Python, Ruby, Perl and others.
Web servers that supports FastCGI are, among others, http://httpd.apache.org/[Apache] and http://nginx.org/[Nginx], and Jetty.
Web servers typically act as proxies, converting HTTP requests that they receive from clients (browsers) to FastCGI requests that are forwarded to the FastCGI server.
The FastCGI server spawns the dynamic web language interpreter, passing it the information contained in the FastCGI request and a dynamic web language script is executed, producing web content, typically HTML.
Web servers that supports FastCGI are, among others, http://httpd.apache.org/[Apache], http://nginx.org/[Nginx], and Jetty.
Web servers typically act as proxies, converting HTTP requests that they receive from clients (browsers) to FastCGI requests that are forwarded to the FastCGI server.
The FastCGI server spawns the dynamic web language interpreter, passing it the information contained in the FastCGI request and a dynamic web language script is executed, producing web content, typically HTML.
The web content is then formatted into a FastCGI response that is returned to the web server, which converts it to a HTTP response that is then returned to the client.
The most well known FastCGI server is the http://php-fpm.org/[PHP FastCGI Process Manager], or `php-fpm`.
The most well known FastCGI server is the http://php-fpm.org/[PHP FastCGI Process Manager], or `php-fpm`.
In the following we will assume that `php-fpm` is used as FastCGI server.
Jetty can be configured to act as a web server that supports FastCGI, replacing the functionality that is normally provided by Apache or Nginx.
Jetty can be configured to act as a web server that supports FastCGI, replacing the functionality that is normally provided by Apache or Nginx.
This allows users to leverage Jetty features such as HTTP/2, the unique support that Jetty provides for HTTP/2 Push, Jetty's scalability, and of course Jetty's native support for Java Web Standards such as Servlets, JSPs, etc.
With such configuration, users can deploy their Java Web Applications in Jetty, but also serve their http://wordpress.com/[WordPress] site or blog or their https://drupal.org/[Drupal] site without having to install and manage multiple web servers.
With such configuration, users can not only deploy their Java Web Applications in Jetty, but also serve their http://wordpress.com/[WordPress] site or blog or their https://drupal.org/[Drupal] site without having to install and manage multiple web servers.