{"id":18044657,"url":"https://github.com/groonga/groonga-nginx","last_synced_at":"2025-10-14T23:38:29.570Z","repository":{"id":182689963,"uuid":"668513859","full_name":"groonga/groonga-nginx","owner":"groonga","description":"nginx based Groonga HTTP server","archived":false,"fork":false,"pushed_at":"2025-02-28T00:49:08.000Z","size":96,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-10T01:06:41.307Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/groonga.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-20T02:03:26.000Z","updated_at":"2025-02-28T00:49:12.000Z","dependencies_parsed_at":"2024-04-26T03:26:54.212Z","dependency_job_id":"7d92b152-2432-4025-9407-7cd318486f15","html_url":"https://github.com/groonga/groonga-nginx","commit_stats":null,"previous_names":["groonga/ngx_http_groonga_module","groonga/groonga-nginx"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groonga%2Fgroonga-nginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groonga%2Fgroonga-nginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groonga%2Fgroonga-nginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groonga%2Fgroonga-nginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/groonga","download_url":"https://codeload.github.com/groonga/groonga-nginx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137887,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-30T18:10:11.336Z","updated_at":"2025-10-14T23:38:29.436Z","avatar_url":"https://github.com/groonga.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# groonga-nginx\n\nThis is a nginx module to use Groonga via HTTP.\n\nThis was formerly distributed with Groonga and provided as `groonga-httpd` with bundled nginx.\n\n## Install\n\nDebian GNU/Linux bookworm or later:\n\n```console\n$ sudo apt install -y -V ca-certificates lsb-release wget\n$ wget https://apache.jfrog.io/artifactory/arrow/$(lsb_release --id --short | tr 'A-Z' 'a-z')/apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb\n$ sudo apt install -y -V ./apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb\n$ rm -f apache-arrow-apt-source-latest-$(lsb_release --codename --short).deb\n$ wget https://packages.groonga.org/debian/groonga-apt-source-latest-$(lsb_release --codename --short).deb\n$ sudo apt install -y -V ./groonga-apt-source-latest-$(lsb_release --codename --short).deb\n$ rm -f groonga-apt-source-latest-$(lsb_release --codename --short).deb\n$ sudo apt update\n$ sudo apt install -y -V libnginx-mod-http-groonga\n$ sudo cp /etc/nginx/groonga.conf /etc/nginx/conf.d/\n$ sudo editor /etc/nginx/conf.d/groonga.conf\n$ sudo systemctl restart nginx\n```\n\nUbuntu 23.10 or later:\n\n```console\n$ sudo apt -y -V install software-properties-common\n$ sudo add-apt-repository -y universe\n$ sudo add-apt-repository -y ppa:groonga/ppa\n$ sudo apt install -y -V libnginx-mod-http-groonga\n$ sudo cp /etc/nginx/groonga.conf /etc/nginx/conf.d/\n$ sudo editor /etc/nginx/conf.d/groonga.conf\n$ sudo systemctl restart nginx\n```\n\n## Configure\n\nYou need to configure your `/etc/nginx/conf.d/groonga.conf` to use this module.\n\n### Basic directives\n\n#### `groonga`\n\nSyntax: `groonga on | off`;\n\nDefault: `groonga off`\n\nContext: `location`\n\nSpecifies whether Groonga is enabled in the ``location`` block. The\ndefault is ``off``. You need to specify ``on`` to enable groonga.\n\nExamples:\n\n```nginx\nlocation /d/ {\n  groonga on;  # Enables groonga under /d/... path\n}\n\nlocation /d/ {\n  groonga off; # Disables groonga under /d/... path\n}\n```\n\n#### `groonga_database`\n\nSyntax: `groonga_database /path/to/groonga/database;`\n\nDefault: None\n\nContext: `main`, `http`, `server`, `location`\n\nSpecifies the path to a Groonga database. This is the required\ndirective.\n\n#### `groonga_database_auto_create`\n\nSyntax: `groonga_database_auto_create on | off;`\n\nDefault: `groonga_database_auto_create on;`\n\nContext: `main`, `http`, `server`, `location`\n\nSpecifies whether Groonga database is created automatically or not. If\nthe value is `on` and the Groonga database specified by\n`groonga-httpd-groonga-database` doesn't exist, the Groonga database\nis created automatically. If the Groonga database exists, this module\ndoes nothing.\n\nIf parent directory doesn't exist, parent directory is also created\nrecursively.\n\nThe default value is `on`. Normally, the value doesn't need to be\nchanged.\n\n#### `groonga_base_path`\n\nSyntax: `groonga_base_path /d/;`\n\nDefault: The same value as `location` name.\n\nContext: `location`\n\nSpecifies the base path in URI. Groonga uses\n`/d/command?parameter1=value1\u0026...` path to run `command`. The form of\npath in used in groonga-nginx but groonga-nginx also supports\n`/other-prefix/command?parameter1=value1\u0026...` form. To support the\nform, groonga-nginx removes the base path from the head of request URI\nand prepend `/d/` to the processed request URI. By the path\nconversion, users can use custom path prefix and Groonga can always\nuses `/d/command?parameter1=value1\u0026...` form.\n\nNomally, this directive isn't needed. It is needed for per command\nconfiguration.\n\nHere is an example configuration to add authorization to\n`shutdown` command:\n\n```nginx\ngroonga_database /var/lib/groonga/db/db;\n\nlocation /d/shutdown {\n  groonga on;\n  # groonga_base_path is needed.\n  # Because /d/shutdown is handled as the base path.\n  # Without this configuration, /d/shutdown/shutdown path is required\n  # to run shutdown command.\n  groonga_base_path /d/;\n  auth_basic           \"manager is required!\";\n  auth_basic_user_file \"/etc/managers.htpasswd\";\n}\n\nlocation /d/ {\n  groonga on;\n  # groonga_base_path doesn't needed.\n  # Because location name is the base path.\n}\n```\n\n#### `groonga_log_path`\n\nSyntax: `groonga_log_path path | off;`\n\nDefault:\n  * `groonga_log_path /var/log/nginx/groonga.log;` for deb packages.\n  * `groonga_log_path logs/groonga.log;` for source build.\n\nContext: `main`, `http`, `server`, `location`\n\nSpecifies Groonga log path in the `main`, `http`, `server` or\n`location` block. The default is `/var/log/nginx/groonga.log` for deb\npackages.  You can disable logging by specifing `off`.\n\nExamples:\n\n```nginx\nlocation /d/ {\n  groonga on;\n  # You can disable log for groonga.\n  groonga_log_path off;\n}\n```\n\n#### `groonga_log_level`\n\nSyntax: `groonga_log_level none | emergency | alert | ciritical | error | warning | notice | info | debug | dump;`\n\nDefault: `notice`\n\nContext: `main`, `http`, `server`, ``location`\n\nSpecifies Groonga log level in the `main`, `http`, `server` or\n`location` block. The default is `notice`. You can disable logging\nby specifying `none` as log level.\n\nExamples:\n\n```nginx\nlocation /d/ {\n  groonga on;\n  # You can customize log level for groonga.\n  groonga_log_level notice;\n}\n```\n\n#### `groonga_query_log_path`\n\nSyntax: `groonga_query_log_path path | off;`\n\nDefault:\n* `groonga_query_log_path  /var/log/nginx/groonga-query.log;` for deb packages.\n* `groonga_query_log_path logs/groonga-query.log;` for source build.\n\nContext: `main`, `http`, `server`, `location`\n\nSpecifies Groonga's query log path in the `main`, `http`, `server` or\n`location` block. The default is `/var/log/nginx/groonga-query.log`\nfor deb packages and `logs/groonga-query.log` for source build. You\ncan disable logging to specify ``off``.\n\nExamples:\n\n```nginx\nlocation /d/ {\n  groonga on;\n  # You can disable query log for groonga.\n  groonga_query_log_path off;\n}\n```\n\nQuery log is useful for the following cases:\n\n  * Detecting slow query.\n  * Debugging.\n\nYou can analyze your query log by [groonga-query-log\npackage](https://github.com/groonga/groonga-query-log). The package\nprovides useful tools.\n\nFor example, there is a tool that analyzing your query log. It can\ndetect slow queries from your query log. There is a tool that\nreplaying same queries in your query log. It can test the new Groonga\nbefore updating production environment.\n\n### Performance related directives\n\nThe following directives are related to the performance of groonga-nginx.\n\n#### `worker_processes`\n\nFor optimum performance, set this to be equal to the number of CPUs or\ncores. In many cases, Groonga queries may be CPU-intensive work, so to\nfully utilize multi-CPU/core systems, it's essential to set this\naccordingly.\n\nThis isn't a groonga-nginx specific directive, but an nginx's one. For\ndetails, see https://nginx.org/en/docs/ngx_core_module.html#worker_processes .\n\nBy default, this is set to 1. It is nginx's default.\n\n#### `groonga_cache_limit`\n\nSyntax: `groonga_cache_limit limit;`\n\nDefault: `groonga_cache_limit 100;`\n\nContext: `main`, `http`, `server`, `location`\n\nSpecifies Groonga's limit of query cache in the `main`, `http`,\n`server` or `location` block. The default value is `100`.  You can\ndisable query cache to specify `0` to ``groonga_cache_limit``\nexplicitly.\n\nExamples:\n\n```nginx\nlocation /d/ {\n  groonga on;\n  # You can customize query cache limit for groonga.\n  groonga_cache_limit 100;\n}\n```\n\n#### `groonga_cache_base_path`\n\nSyntax: `groonga_cache_base_path path | off;`\n\nDefault: `groonga_cache_base_path off;`\n\nContext: `main`, `http`, `server`, `location`\n\nSpecifies the base path of query cache in the `main`, `http`, `server`\nor `location` block.\n\nIt's recommended that you specify this configuration when you use\nmulti-workers configuration.\n\nIf the base path is specified, you can use persistent cache instead of\non memory cache. If you use persistent cache, workers share query\ncache. It's efficient for multi-workers configuration because the same\nresponse is cached only once in multiple workers.\n\nThere is one more merit for persistent cache. You don't need to warm\nup cache after groonga-httpd is restarted. Persistent cache isn't\ncleared when groonga-httpd is down. groonga-httpd can use existing\npersistent cache again.\n\nThe default value is `off`. It means that persistent cache is\ndisabled. On memory cache is used. On memory cache is independent in\neach worker. It's not efficient for multi-workers configuration\nbecause two or more workers may keeps the same response separately.\n\nPersistent cache is a bit slower than on memory cache. Normally, the\ndifference has little influence on performance.\n\nYou must specify the base path on memory file system. If you specify\nthe base path on disk, your cache will be slow. It's not make sense.\n\nExamples:\n\n```nginx\nlocation /d/ {\n  groonga on;\n  # You can customize query cache limit for groonga.\n  groonga_cache_base_path /dev/shm/groonga-httpd-cache;\n}\n```\n\n## For developers\n\n### Upload to the `ppa` repository\n\n1. Follow the [PGroonga documentation](https://pgroonga.github.io/development/release.html#requirements) and do the required setup\n   * The environment variables used in this repository are `GROONGA_REPOSITORY`, `LAUNCHPAD_UPLOADER_PGP_KEY` and `APACHE_ARROW_REPOSITORY`\n2. Install `nginx-dev`\n   * Install `nginx-dev` as it is also required\n   * Note: The working machine must be Ubuntu 24.04+ or for Debian bookworm+\n3. Upload\n   * Run in the repository root directory\n     ```bash\n     rake package:ubuntu\n     ```\n\n## License\n\nLGPLv2.1 or later.\n\nSee [COPYING](COPYING) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroonga%2Fgroonga-nginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroonga%2Fgroonga-nginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroonga%2Fgroonga-nginx/lists"}