.. -*- rst -*-

.. highlightlang:: none

groonga-httpd
=============

Summary
-------

groonga-httpd is a program to communicate with a groonga server using
the HTTP protocol. It functions as same as
:doc:`groonga-server-http`. Although :doc:`groonga-server-http` has
limited support for HTTP with a minimal built-in HTTP server,
groonga-httpd has full support for HTTP with an embedded `nginx
<http://nginx.org/>`_. All standards-compliance and features provided
by nginx is also available in groonga-httpd.

groonga-httpd has an Web-based administration tool implemented with HTML and
JavaScript. You can access to it from http://hostname:port/.

Synopsis
--------

::

  groonga-httpd [nginx options]

Usage
-----

Set up
^^^^^^

First, you'll need to edit the groonga-httpd configuration file to specify a
database. Edit /etc/groonga/httpd/groonga-httpd.conf to enable the
``groonga_database`` directive like this::

   # Match this to the file owner of groonga database files if groonga-httpd is
   # run as root.
   #user groonga;
   ...
   http {
     ...
     # Don't change the location; currently only /d/ is supported.
     location /d/ {
       groonga on; # <= This means to turn on groonga-httpd.

       # Specify an actual database and enable this.
       groonga_database /var/lib/groonga/db/db;
     }
     ...
   }

Then, run groonga-httpd. Note that the control immediately returns back to the
console because groonga-httpd runs as a daemon process by default.::

   % groonga-httpd

Request queries
^^^^^^^^^^^^^^^

To check, request a simple query (:doc:`/reference/commands/status`).

.. groonga-command
.. database: groonga-httpd
.. include:: ../../example/reference/executables/groonga-httpd.log
.. /d/status

Browse the administration tool
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Also, you can browse Web-based administration tool at http://localhost:10041/.

Shut down
^^^^^^^^^

Finally, to terminate the running groonga-httpd daemon, run this::

   % groonga-httpd -s stop

Configuration directives
------------------------

This section decribes only important directives. They are
groonga-httpd specific directives and performance related directives.

The following directives can be used in the groonga-httpd configuration file.
By default, it's located at /etc/groonga/httpd/groonga-httpd.conf.

Groonga-httpd specific directives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following directives aren't provided by nginx. They are provided
by groonga-httpd to configure groonga-httpd specific configurations.

``groonga``
"""""""""""

Synopsis::

  groonga on | off;

Default
  ``groonga off;``

Context
  ``location``

Specifies whether groonga is enabled in the ``location`` block. The
default is ``off``. You need to specify ``on`` to enable groonga.

Examples::

  location /d/ {
    groonga on;  # Enables groonga under /d/... path
  }

  location /d/ {
    groonga off; # Disables groonga under /d/... path
  }

``groonga_database``
""""""""""""""""""""

Synopsis::

  groonga_database /path/to/groonga/database;

Default
  ``groonga_database /usr/local/var/lib/groonga/db/db;``

Context
  ``http``, ``server``, ``location``

Specifies the path to a groonga database. This is the required
directive.

``groonga_base_path``
"""""""""""""""""""""

Synopsis::

  groonga_base_path /d/;

Default
  The same value as ``location`` name.

Context
  ``location``

Specifies the base path in URI. groonga uses
``/d/command?parameter1=value1&...`` path to run ``command``. The form
of path in used in groonga-httpd but groonga-httpd also supports
``/other-prefix/command?parameter1=value1&...`` form. To support the
form, groonga-httpd removes the base path from the head of request URI
and prepend ``/d/`` to the processed request URI. By the path
conversion, users can use custom path prefix and groonga can always
uses ``/d/command?parameter1=value1&...`` form.

Nomally, this directive isn't needed. It is needed for per command
configuration.

Here is an example configuration to add authorization to
:doc:`/reference/commands/shutdown` command::

  groonga_database /var/lib/groonga/db/db;

  location /d/shutdown {
    groonga on;
    # groonga_base_path is needed.
    # Because /d/shutdown is handled as the base path.
    # Without this configuration, /d/shutdown/shutdown path is required
    # to run shutdown command.
    groonga_base_path /d/;
    auth_basic           "manager is required!";
    auth_basic_user_file "/etc/managers.htpasswd";
  }

  location /d/ {
    groonga on;
    # groonga_base_path doesn't needed.
    # Because location name is the base path.
  }

Performance related directives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following directives are related to the performance of groonga-httpd.

``worker_processes``
""""""""""""""""""""

For optimum performance, set this to be equal to the number of CPUs or cores. In
many cases, groonga queries may be CPU-intensive work, so to fully utilize
multi-CPU/core systems, it's essential to set this accordingly.

This isn't a groonga-httpd specific directive, but an nginx's one. For details,
see http://wiki.nginx.org/CoreModule#worker_processes.

By default, this is set to 1. It is nginx's default.

Available nginx modules
-----------------------

All standard HTTP modules is available. HttpRewriteModule is
disabled when you don't have PCRE (Perl Compatible Regular
Expressions). For the list of standard HTTP modules, see
http://wiki.nginx.org/Modules.