Installing Pivotal Web Server

Pivotal Web Server has several options for installation and setup. Installation options vary according to whether your operating system is Unix, Windows, or another supported platform.

Subtopics

Available Distribution Packages

RHEL: Install Pivotal Web Server from an RPM

Unix: Install Pivotal Web Server from a Self-Extracting ZIP

Windows: Install Pivotal Web Server from a Self-Extracting ZIP File

Description of the Pivotal Web Server Installation

Available Distribution Packages

Pivotal Web Server is split into the following two distribution packages to simplify the installation and deployment to your datacenter:

  • pivotal-web-server: Base package entirely sufficient for all production environments.
  • pivotal-web-server-devel: Supplemental package that developers can use to compile and link http modules with the same headers and libraries as httpd itself using the httpd- 2.4 /bin/apxs tool. This package requires that you also install the base package.

RHEL - Install Pivotal Web Server from an RPM

Pivotal recommends that you install Pivotal Web Server on a Red Hat Linux Enterprise (RHEL) computer by first installing the Pivotal RPM repository and then using yum to perform the actual installation. See Install Pivotal Web Server from the Pivotal RPM Repository.

You can also download the RPM from the Pivotal download page, and install it on your RHEL computer using the rpm command, as described in Install Pivotal Web Server from a Downloaded RPM.

Install Pivotal Web Server from the Pivotal RPM Repository

Pivotal recommends that you install Web Server on RHEL computers using the Pivotal RPM repository.

Prerequisites

  • Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements.
  • Install the Pivotal repository RPM, which makes it easier for you to browse the Pivotal RPMs, including the Pivotal Web Server RPM. You install the Pivotal repository RPM on each RHEL computer on which you want to install one or more Pivotal products, such as Pivotal tc Server.

    1. On the RHEL computer, start a terminal as the root user.
    2. Install the Pivotal repository RPM using the following wget command, passing it the appropriate URL. The URL differs depending on the version of RHEL you are using.

      Important: You must run the entire wget command on a single line. Be sure you include the | sh at the end, or the RPM installation will not work.

      RHEL 5:

      prompt# wget -q -O - http://packages.pivotal.io/pub/rpm/rhel5/app-suite/app-suite-installer | sh 
      

      RHEL 6:

      prompt# wget -q -O - http://packages.pivotal.io/pub/rpm/rhel6/app-suite/app-suite-installer | sh 
      

      The command performs the following tasks:

      • Imports the Pivotal GNU Privacy Guard (GPG) key.
      • Launches the Pivotal End User License Agreement (EULA) acceptance and repository configuration script.
      • Outputs the EULA for you to read; you must answer yes to accept the terms and continue.
    3. Use the yum search pivotal command to view the list of Pivotal products that you can install from the Pivotal repository. For example (output truncated for clarity):

      prompt# yum search pivotal
      ...
      ======================================== Matched: pivotal ========================================
      pivotal-rabbitmq-java-client-bin.noarch : The RabbitMQ Java Client Library
      pivotal-rabbitmq-server.x86_64 : The RabbitMQ server
      pivotal-tc-server-standard.noarch : Pivotal tc Server Standard
      pivotal-web-server.x86_64 : Pivotal Web Server
      ...
      

      The Pivotal Web Server RPM is called pivotal-web-server.

Procedure

  1. From the RHEL computer on which you will install Pivotal Web Server, log in as the root user and start a terminal.
  2. Execute the following yum command:

    prompt# yum install pivotal-web-server 
    

    The yum command begins the install process, resolves dependencies, and displays the packages it will install.

    The yum command automatically chooses the appropriate RPM package based on your architecture (32- or 64-bit).

    To install the developer’s package:

    prompt# yum install pivotal-web-server-devel 
    
  3. Enter y at the prompt to begin the actual installation.

    If the installation is successful, you see a Complete! message at the end.

What the yum install command does

The yum install command:

  • Installs Pivotal Web Server into the /opt/pivotal/webserver directory.
  • Sets the owner of installation directory, along with all child directories and files, to root:root.

What to do next

Install Pivotal Web Server From a Downloaded RPM

You can install Pivotal Web Server on RHEL by downloading the RPM from the Pivotal download center and executing the rpm command.

Prerequisites

Procedure

  1. Log in to the RHEL computer on which you will install Pivotal Web Server as the root user.
  2. Navigate to the Pivotal Web Server download page.
  3. Download the Web Server RPM file to a directory on your computer. The RPM file is called pivotal-web-server-version.architecture.rpm.
  4. Start a terminal and change to the directory in which you downloaded the RPM.
  5. Execute the following rpm command to install Web Server:

    prompt# rpm -ivhf pivotal-web-server-version.architecture.rpm
    
  6. In the previous section, see What the yum install command does for post-installation information, such as the installation directory. (The yum install command corresponds to the rpm command in this procedure.)

Unix - Install Pivotal Web Server from a Self-Extracting ZIP

You can install Pivotal Web Server on Unix computers with a self-extracting ZIP file that you download from the Pivotal Web site. Self-extracting zip files expand themselves, or you can use unzip if your platform supports it. Using unzip explicitly enables you to specify options in addition to what is executed by default when the ZIP self-extracts.

Prerequisites

  • Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements.
  • If you want to use unzip so you can specify additional options, but your platform does not support unzip, obtain an unzip command.
  • If your operating system is configured to support only 64-bit operation, an external unzip utility is required. Do not use the jar utility to unpack these zip files, because the file system permissions will not be unpacked correctly.
  • Be sure you have installed Perl on your computer, and that it is at least version 5.8. Pivotal recommends that you run the Perl script (described in the procedure) in multibyte character encoding such as UTF-8, especially if you are an international customer.

Procedure

  1. Log in as the root user on to the Unix computer on which you want to install Pivotal Web Server.
  2. Create the directory in which you will install Pivotal Web Server. For example:

    prompt# mkdir /opt/pivotal
    
  3. Navigate to the Pivotal Web Server download page.

  4. Download the appropriate Pivotal Web Server self-extracting ZIP, and place it in the directory you created.

    Be sure to choose the correct Unix operating system and chip architecture. For example, the file to install Pivotal Web Server on a 64-bit Linux platform is pivotal-web-server-version-x86_64-linux-glibc2.zip.sfx.

  5. From your terminal window, change to the directory in which you downloaded the ZIP file:

    prompt# cd /opt/pivotal 
    
  6. If necessary, change the permissions of the downloaded ZIP file to make it executable:

    prompt# chmod +x pivotal-web-server-version-x86_64-linux-glibc2.zip.sfx 
    
  7. Self-extract the files from the downloaded ZIP by using the file name as a command. For example:

    prompt# ./pivotal-web-server-version-x86_64-linux-glibc2.zip.sfx 
    

    When it completes, the Pivotal Web Server files are located in the webserver subdirectory.

  8. Change to the webserver directory and run the fixrootpath.pl Perl script to correct the root paths. For example:

    prompt# cd webserver
    prompt# perl fixrootpath.pl 
    

What to do next

Windows - Install Pivotal Web Server from a ZIP File

You install Pivotal Web Server on Windows computers using a self-extracting ZIP file (*.zip.exe) that you download from the Pivotal Web site.

Prerequisites

  • Verify that your system meets the supported configurations and installation requirements. See Supported Configurations and System Requirements.
  • You must use Windows PowerShell 2.0 to execute the Pivotal Web Server scripts on Windows computers. Most recent Windows versions have PowerShell installed by default, but some older versions of Windows do not. To check whether your version of Windows has PowerShell installed, go to Start > All Programs > Accessories and check for Windows PowerShell in the list.

    If Windows PowerShell 2.0 is not installed on your Windows computer, download and install it from the Windows Management Framework (Windows PowerShell 2.0, WinRM 2.0, and BITS 4.0) Web page on the Microsoft Support.

  • If necessary, enable Windows PowerShell for script processing; by default, script processing is disabled.

    1. Start PowerShell from the Start Menu as an Administrator by opening Start > All Programs > Accessories > Windows PowerShell, then right-clicking on Windows PowerShell and selecting Run as Administrator. A PowerShell window starts.
    2. Check the current PowerShell setting by executing the following command:

      PS prompt> Get-ExecutionPolicy 
      

      If the command returns Restricted, it means that PowerShell is not yet enabled. Enable it to allow local script processing at a minimum by executing the following command:

      PS prompt> Set-ExecutionPolicy RemoteSigned 
      

      You can choose a different execution policy for your organization if you want, as well as enable PowerShell using Group and User policies. Typically, only the Administrator will be using the Pivotal Web Server scripts, so the RemoteSigned execution policy should be adequate in most cases.

Procedure

  1. From the Windows computer on which you want to install Pivotal Web Server, log in as the Administrator user.
  2. Start PowerShell from the Start Menu as an Administrator by opening Start > All Programs > Accessories > Windows PowerShell, then right-clicking on Windows PowerShell and selecting Run as Administrator. A PowerShell window starts.
  3. Create the directory into which you will install Pivotal Web Server. Do not create a directory name that contains spaces. For example:

    PS prompt> mkdir c:\opt\pivotal
    
  4. Navigate to the Pivotal Web Server download page.

  5. Download the appropriate Pivotal Web Server self-extracting ZIP, and place it in the directory you created.

    Be sure to choose the correct architecture (32- or 64-bit). For example, the file to install Pivotal Web Server on a 64-bit Windows platform is pivotal-web-server-version-x64-windows.zip.exe.

  6. Execute the downloaded *.zip.exe file to self-extract the files into the directory you created. You can do this, for example, by opening Window Explorer, navigating to the directory, and double-clicking on the *.zip.exe file.

    When the extraction completes, the Pivotal Web Server files are located in the webserver subdirectory.

  7. From your command window, change to the main Pivotal Web Server directory:

    PS prompt> cd c:\opt\pivotal\webserver
    
  8. Run the fixrootpath.ps1 PowerShell script to correct the root paths:

    PS prompt> .\fixrootpath.ps1
    
  9. Create a symbolic link from the existing httpd- 2.4.version directory to one called httpd- 2.4 , where version refers to the minor version and architecture of Pivotal Web Server.

    PowerShell does not include mklink intrinsically, so you must use the command cmd /c mklink. For example, to use the 64-bit edition of Pivotal Web Server, run the following command:

    PS prompt> cmd /c mklink /d httpd-
    
                               2.4
                             httpd-
    
                               2.4.10
                            .0-64 
    

What to do next

Description of the Pivotal Web Server Installation

The main Pivotal Web Server directory structure, although similar in many ways to the standard Apache HTTP directory layout, differs from it in a very fundamental way: Pivotal Web Server separates the runtime binaries from the configuration data.

To implement this separation, you use the newserver command to create a Pivotal Web Server instance that lives in a subdirectory of the main Pivotal Web Server home directory. The name of the instance is the name of the new subdirectory. You then configure this instance as you want, using the standard Apache httpd files in the server-name/conf directory, such as httpd.conf. Note: Perform all configuration work inside the server instance (server-name/conf) directory. Never modify any files under the binary directory (such as httpd- 2.4).

Keeping the runtime binary files apart from the files that are configured by administrators or end users makes it easier to upgrade or apply patches to the code without the risk of overwriting or corrupting user data. It also enables administrators to run multiple server instances independently.

Directly after installing Pivotal Web Server, you see the following files and directories:

  • httpd- 2.4/ : Symbolic link to a sibling directory that actually contains the Apache 2.4 binary runtime files.
  • httpd- 2.4.version/ : Directory that contains the actual Apache 2.4 binary runtime files. The string specifies the Apache HTTP version, such as 2.4.10 or 2.4.10-64.
  • licenses/ : EULA and open source license files.
  • newserver : (Unix) Perl script for creating Pivotal Web Server instances.
  • newserver.ps1 : (Windows) PowerShell script for creating Pivotal Web Server instances.
  • fixrootpath.pl : (Unix) Perl script for fixing root paths; run only once.
  • fixrootpath.ps1 : (Windows) PowerShell script for fixing root paths; run only once.

After you use newserver to create a new Pivotal Web Server instance, the command creates a new directory that contain a separately configurable instance of Pivotal Web Server. An instance is a complete, discrete server configuration. You can create multiple instances. You can run multiple instances at the same time if you are careful not to use the same ports in two different instances. For example, the default HTTP listening port is 80, and only one instance on any computer is allowed to communicate on port 80 at any one time. So if you wanted to have two Pivotal Web Server instances running at the same time on the same computer, you would configure one instance to use a port other than 80.

Each instance directory contains subdirectories that contain all the data required to run a given Pivotal Web Server instance. This includes configuration data as well as all other data that is associated with that instance’s configuration. For example, assume you installed Pivotal Web Server in /opt/pivotal/webserver and create an instance called myserver:

prompt$ cd /opt/pivotal/webserver/myserver
prompt$ ls
bin  cgi-bin  conf  ftpdocs  htdocs  logs  proxy ssl  var

The conf directory contains the Pivotal Web Server configuration files, such as httpd.conf. The bin directory contains the startup script used to start and stop the myserver instance (httpdctl). Each of these directories is specific to the myserver instance. Each instance that you create has a similar set of directories.