The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

OpenResty::Spec::Install - Installation instructions for OpenResty servers

DESCRIPTION

This is a basic guideline for settting up an OpenResty server on your own machine. Someone has succeeded in setting up one on Windows XP using ActivePerl 5.8.8. The normal development environment is Linux though. If you have any particular question, feel free to ask us by sending an email to the authors.

  1. Grab the openresty package and unpack it to some place, let's say it's openresty.

  2. Enter the openresty directory, run "perl Makefile.PL" to check missing dependencies:

        $ cd openresty
        $ perl Makefile.PL
        $ sudo make  # This will install missing dependencies
        $ make test  # run the test suite using the PgMocked backend

    For the PostgreSQL database, you need to prepare a PostgreSQL account (e.g. "agentzh"); and you need to create an empty database (e.g., "test"), and you need to create a stored precedure language named "plpgsql" for that database, contact your PostgreSQL DBA for it or read the PostgreSQL manual.

    Normally, the following commands are used:

        $ createdb test
        $ createuser -P agnetzh
        $ createlang plpgsql test
  3. Edit your etc/site_openresty.conf file, change the configure settings under [backend] section according to your previous settings. The default settings look like this:

        [backend]
        recording=0
        # You should change the line below to type=Pg or type=PgFarm
        type=PgMocked
        host=localhost
        user=agentzh
        password=agentzh
        database=test

    Most of the time, you need to change type=PgMocked to type=Pg, as well as the last 3 lines (unless you're using exactly the same user, password, and database name). The default "PgMocked" backend is a mocked PostgreSQL database which is useful only for testing purposes.

  4. For the Pg backend, one needs to create the "anonymous" role in his database (like "test"):

        $ createuser -RSDL anonymous

    You shouldn't grant any permissions to it.

  5. Create a "tester" user account for our test suite in OpenResty (drop it if it already exists):

        $ bin/openresty deluser tester
        $ bin/openresty adduser tester

    Give a password (say, "password") to its Admin role. Also create a second user account "tester2":

        $ bin/openresty adduser tester2

    Update your etc/site_openresty.conf to reflect your these settings:

        [test_suite]
        use_http=0
        server=tester:password@localhost
        server2=tester2:password@localhost

    You may have your own passwords here though.

  6. To have OpenResty's built-in actions RunView and RunAction working, you need to build the restyscript compiler in the subdirectory haskell/. It is written in Haskell and please see the README file in haskell/ for detailed installation instruction:

    http://svn.openfoundry.org/openapi/trunk/haskell/README

    If you're really nervous about installing GHC and other Haskell libraries, you can fetch a binary version of the restyscript compiler if you're on an 32-bit x86 linux:

        $ wget 'http://openresty.org/restyscript' -O haskell/bin/restyscript
        $ chmod +x haskell/bin/restyscript

    A quick test would be

        $ echo 'select 3' | haskell/bin/restyscript view rs
        select 3
  7. Now you can already run the test suite without a lighttpd server (but with a true Pg backend):

        $ make test

    Also, it's already possible to start the OpenResty server using the standalone server provided by HTTP::Server::Simple:

        $ bin/openresty start
        HTTP::Server::Simple: You can connect to your server at http://localhost:8000/
  8. Sample lighttpd configuration:

        # lighttpd.conf
    
        server.modules              = (
                    "mod_fastcgi",
                    ...
        )
    
        fastcgi.server = (
            "/=" => (
                "openresty" => (
                    "socket"       => "/tmp/openresty.socket",
                    "check-local"  => "disable",
                    "bin-path"     => "/PATH/TO/YOUR/bin/openresty",
                    "bin-environment" => (
                        "OPENRESTY_URL_PREFIX" => "",
                        "OPENRESTY_COMMAND" => "fastcgi",
                    ),
                    "min-procs"    => 1,
                    "max-procs"    => 5,
                    "max-load-per-proc" => 1,
                    "idle-timeout" => 20,
                )
            )
        )

    And also make sure the following line is commented out:

        # url.access-deny            = ( "~", ".inc" )

HOW TO TEST ONE SPECIFIC TEST SUITE FILE

It's also possible to debug a simple .t file, for instance,

    make t/01-sanity.t -f dev.mk

Or use the OPENRESTY_TEST_SERVER environment to test a remote OpenResty server, for example:

    OPENRESTY_TEST_SERVER=teser:password@10.62.136.86 prove -Ilib -r t

where 10.62.136.86 is the IP (or hostname or URL) of your OpenResty server being tested.

To test the Pg cluster rather than the desktop Pg, update your etc/site_openresty.conf:

    [backend]
    type=PgFarm

and also set other items in the same group if necessary.

SYSTEM-WIDE INSTALLATION

Some times it's desired to do "sudo make install" and install all the OpenResty modules and command line tools to the system-wide perl.

The steps are simple:

  1. Build the haskell/bin/restyscript program

  2. The usual CPAN module installation process:

        perl Makefile.PL
        make
        sudo make install
  3. Copy the config files to /etc/openresty/. Essentially, it is

        mkdir /etc/openresty
        cp etc/*.conf /etc/openresty/
  4. Now you can test your installation by starting the standalone server for OPenResty:

        openresty start

AUTHOR

Agent Zhang (agentzh) <agentzh@yahoo.cn>, Laser Henry (laser) <laserhenry@gmail.com>.

SEE ALSO

openresty, OpenResty::Config, OpenResty::Spec::AccountAdmin, OpenResty::Spec::Upgrading, OpenResty::Spec::TestSuite, OpenResty.