groonga - An open-source fulltext search engine and column store.

7.1.4. groonga-httpd

7.1.4.1. Summary

groonga-httpd is a program to communicate with a groonga server using the HTTP protocol. It functions as same as groonga HTTPサーバー. Although groonga HTTPサーバー has limited support for HTTP with a minimal built-in HTTP server, groonga-httpd has full support for HTTP with an embedded nginx. All standards-compliance and features provided by nginx is also available in groonga-httpd. For details about nginx, see http://www.nginx.org/

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

7.1.4.2. Synopsis

groonga-httpd [nginx options]

7.1.4.3. Usage

7.1.4.3.1. 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

7.1.4.3.2. Request queries

To check, request a simple query (status).

Execution example:

% curl http://localhost:10041/d/status
[
  [
    0,
    1337566253.89858,
    0.000355720520019531
  ],
  {
    "uptime": 0,
    "max_command_version": 2,
    "n_queries": 0,
    "cache_hit_rate": 0.0,
    "version": "2.0.3-278-g6071d65",
    "alloc_count": 145,
    "command_version": 1,
    "starttime": 1340769698,
    "default_command_version": 1
  }
]

7.1.4.3.3. Browse the administration tool

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

7.1.4.3.4. Shut down

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

% groonga-httpd -s stop

7.1.4.4. 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.

7.1.4.4.1. Groonga-httpd specific directives

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

7.1.4.4.1.1. 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
}

7.1.4.4.1.2. 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.

7.1.4.4.1.3. 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 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.
}

7.1.4.5. Available nginx modules

All standard HTTP modules except HttpRewriteModule is available. HttpRewriteModule is disabled to avoid to depend on PCRE (Perl Compatible Regular Expressions). For the list of other standard HTTP modules, see http://wiki.nginx.org/Modules.