{"id":13512036,"url":"https://github.com/openresty/opm","last_synced_at":"2025-03-30T22:31:51.906Z","repository":{"id":11182485,"uuid":"68239979","full_name":"openresty/opm","owner":"openresty","description":"OpenResty Package Manager","archived":false,"fork":false,"pushed_at":"2024-05-20T06:27:59.000Z","size":551,"stargazers_count":461,"open_issues_count":29,"forks_count":75,"subscribers_count":27,"default_branch":"master","last_synced_at":"2024-11-01T14:36:48.234Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://opm.openresty.org/","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openresty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2016-09-14T20:17:39.000Z","updated_at":"2024-10-23T01:23:28.000Z","dependencies_parsed_at":"2024-11-01T14:30:27.703Z","dependency_job_id":"00df902a-c006-4745-9cc0-6e72479094bf","html_url":"https://github.com/openresty/opm","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fopm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fopm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fopm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Fopm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openresty","download_url":"https://codeload.github.com/openresty/opm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246390896,"owners_count":20769475,"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-08-01T03:01:26.105Z","updated_at":"2025-03-30T22:31:51.205Z","avatar_url":"https://github.com/openresty.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"Name\n====\n\nopm - OpenResty Package Manager\n\nTable of Contents\n=================\n\n* [Name](#name)\n* [Status](#status)\n* [Synopsis](#synopsis)\n* [Description](#description)\n* [Usage](#usage)\n    * [Global Installation](#global-installation)\n    * [Local Installation](#local-installation)\n* [HTTP Proxy Support](#http-proxy-support)\n* [Author Workflow](#author-workflow)\n* [File dist.ini](#file-distini)\n    * [name](#name)\n    * [abstract](#abstract)\n    * [version](#version)\n    * [author](#author)\n    * [license](#license)\n    * [requires](#requires)\n    * [repo_link](#repo_link)\n    * [is_original](#is_original)\n    * [lib_dir](#lib_dir)\n    * [exclude_files](#exclude_files)\n    * [main_module](#main_module)\n    * [doc_dir](#doc_dir)\n* [File .opmrc](#file-opmrc)\n    * [github_account](#github_account)\n    * [github_token](#github_token)\n    * [upload_server](#upload_server)\n    * [download_server](#download_server)\n* [Version Number Handling](#version-number-handling)\n* [Installation](#installation)\n    * [For opm](#for-opm)\n* [Security Considerations](#security-considerations)\n* [Credit](#credit)\n* [TODO](#todo)\n* [Author](#author)\n* [Copyright and License](#copyright-and-license)\n\nStatus\n======\n\nExperimental.\n\nSynopsis\n========\n\nFor library users:\n\n```bash\n# show usage\nopm --help\n\n# search package names and abstracts with the user pattern \"lock\".\nopm search lock\n\n# search package names and abstracts with multiple patterns \"lru\" and \"cache\".\nopm search lru cache\n\n# install a package named lua-resty-foo under the name of some_author\nopm get some_author/lua-resty-foo\n\n# get a list of lua-resty-foo packages under all authors.\nopm get lua-resty-foo\n\n# show the details of the installed package specified by name.\nopm info lua-resty-foo\n\n# show all the installed packages.\nopm list\n\n# upgrade package lua-resty-foo to the latest version.\nopm upgrade lua-resty-foo\n\n# update all the installed packages to their latest version.\nopm update\n\n# uninstall the newly installed package\nopm remove lua-resty-foo\n```\n\nAll the commands can follow the `--cwd` option to work in the current working\ndirectory (under ./resty/modules/) instead of the system-wide location.\n\n```bash\n# install into ./resty_modules/ instead of the system-wide location:\nopm --cwd get foo/lua-resty-bar\n\n# check the locally installed packages under ./resty_modules/\nopm --cwd list\n\n# remove the locally installed packages under ./resty_modules/\nopm --cwd remove lua-resty-bar\n```\n\nFor library authors:\n\n```bash\ncd /path/to/lua-resty-foo/\n\nopm build\n\n# optional:\n#     cd lua-resty-foo-VERSION/ \u0026\u0026 opm server-build\n\n# you may need to edit the ~/.opmrc file to set up your github\n# personal access tokens. the first run of \"opm upload\" will create\n# a boilerplate ~/.opmrc file for you.\nopm upload\n\n# cleaning up the leftovers of the opm build command.\nopm clean dist\n```\n\nDescription\n===========\n\n`opm` is the official OpenResty package manager, similar to\nPerl's CPAN and NodeJS's npm in rationale.\n\nWe provide both the `opm` client-side command-line utility and\nthe server-side application for the central package repository in this\nGitHub code repository.\n\nThe `opm` command-line utility can be used by OpenResty users to download\npackages published on the central `opm` server (i.e., `opm.openresty.org`).\nIt can also be used to package and upload the OpenResty package to the server\nfor package authors and maintainers. You can find the source of `opm` under\nthe `bin/` directory. It is currently implemented as a standalone Perl script.\n\nThe server side web application is built upon OpenResty and written in Lua.\nYou can find the server code under the `web/` directory.\n\nUnlike many other package management systems like `cpan`, `luarocks`, `npm`,\nor `pip`. Our `opm` adopts a package naming discipline similar to `github`, that\nis, every package name should be qualified by a publisher ID, as in\n`agentzh/lua-resty-foo` where `agentzh` is the publisher ID while `lua-resty-foo`\nis the package name itself. This naming requirement voids the temptation of\noccupying good package names and also allows multiple same-name libraries to\ncoexist in the same central server repository. It is up to the user to decide\nwhich library to install (or even install multiple forks of the same library\nin different projects of hers). For simplicity, we simply map the GitHub\nuser IDs and organization IDs to the publisher IDs for `opm`. For this reason,\nwe use the GitHub personal access tokens (or oauth tokens) to authenticate\nour package publishers. This also eliminates the sign-up process for `opm`\npackage authors altogether.\n\n`opm` has built-in support for the `restydoc` tool, that is, the documentation\nof the packages installed via `opm` is already indexed by `restydoc` and can\nbe viewed directly on the terminal with the `restydoc` tool.\n\n`opm` currently only supports pure Lua libraries but we will add support for\nLua libraries in pure C or with some C components very soon. The vision is\nto also add support for redistributing 3rd-party NGINX C modules as dynamic\nNGINX modules via `opm` in the future. The OpenResty world consists of various\ndifferent kinds of \"modules\" after all.\n\nWe also have plans to allow the user to install LuaRocks packages via `opm`\nthrough the special user ID `luarocks`. It poses a risk of installing\nan OpenResty-agnostic Lua module which blocks the NGINX worker processes\nhorribly on network I/O, nevertheless, as the developers of `opm`, we always like choices,\nespecially those given to our users.\n\n[Back to TOC](#table-of-contents)\n\nUsage\n=====\n\n```\nopm [options] command package...\n\nOptions:\n    -h\n    --help              Print this help.\n\n\n    --install-dir=PATH  Install into the specified PATH directory instead of the system-wide\n                        OpenResty installation tree containing this tool.\n\n    --cwd               Install into the current working directory under ./resty_modules/\n                        instead of the system-wide OpenResty installation tree containing\n                        this tool.\n\nCommands:\n    build               Build from the current working directory a package tarball ready\n                        for uploading to the server.\n\n    clean ARGUMENT...   Do clean-up work. Currently the valid argument is \"dist\", which\n                        cleans up the temporary files and directories created by the \"build\"\n                        command.\n\n    info PACKAGE...     Output the detailed information (or meta data) about the specified\n                        packages.  Short package names like \"lua-resty-lock\" are acceptable.\n\n    get PACKAGE...      Fetch and install the specified packages. Fully qualified package\n                        names like \"openresty/lua-resty-lock\" are required. One can also\n                        specify a version constraint like \"=0.05\" and \"\u003e=0.01\".\n\n    list                List all the installed packages. Both the package names and versions\n                        are displayed.\n\n    remove PACKAGE...   Remove (or uninstall) the specified packages. Short package names\n                        like \"lua-resty-lock\" are acceptable.\n\n    search QUERY...     Search on the server for packages matching the user queries in their\n                        names or abstracts. Multiple queries can be specified and they must\n                        fulfilled at the same time.\n\n    server-build        Build a final package tarball ready for distribution on the server.\n                        This command is usually used by the server to verify the uploaded\n                        package tarball.\n\n    update              Update all the installed packages to their latest version from\n                        the server.\n\n    upgrade PACKAGE...  Upgrade the packages specified by names to the latest version from\n                        the server. Short package names like \"lua-resty-lock\" are acceptable.\n\n    upload              Upload the package tarball to the server. This command always invokes\n                        the build command automatically right before uploading.\n```\n\n[Back to TOC](#table-of-contents)\n\nGlobal Installation\n-------------------\n\nTo globally install opm packages, just use the `sudo opm get foo/bar` command.\n\n[Back to TOC](#table-of-contents)\n\nLocal Installation\n------------------\n\nWhen you use `--cwd` option to install packages to the `./resty_modules/` directory, then you should\nput the following lines to your `nginx.conf`, inside the `http {}` block:\n\n```nginx\nlua_package_path \"$prefix/resty_modules/lualib/?.lua;;\";\nlua_package_cpath \"$prefix/resty_modules/lualib/?.so;;\";\n```\n\nDo NOT change `$prefix` to a hard-coded absolute path yourself! OpenResty will automatically resolve the\nspecial `$prefix` variable in the directive values at startup. The `$prefix` value will be resolved\nto the server prefix, which will later be specified via the `-p` option of the `openresty` command\nline.\n\nAnd then you should start your OpenResty application from the current working directory like this:\n\n```bash\nopenresty -p $PWD/\n```\n\nassuming you have the following OpenResty application directory layout in the current directory:\n\n```\nlogs/\nconf/\nconf/nginx.conf\nresty_modules/\n```\n\nAlternatively, if you just want to use the `resty` command line utility with the opm modules installed\ninto the `./resty_modules` directory, then you should just use the `-I ./resty_modules/lualib` option, as in\n\n```bash\nresty -I ./resty_modules/lualib -e 'require \"foo.bar\".go()'\n```\n\n[Back to TOC](#table-of-contents)\n\nHTTP Proxy Support\n==================\n\nHTTP proxies are supported via the `http_proxy` and `https_proxy` system environment variables, as in\n\n```\nhttp_proxy [protocol://]\u003chost\u003e[:port]\n\t  Sets the proxy server to use for HTTP.\n\nhttps_proxy [protocol://]\u003chost\u003e[:port]\n\t  Sets the proxy server to use for HTTPS.\n```\n\n[Back to TOC](#table-of-contents)\n\nAuthor Workflow\n===============\n\nThe package author should put a meta-data file named `dist.ini` on the top-level of the Lua library source tree.\nThis file is used by the `opm build` command to build and package up your library into a tarball file which can be\nlater uploaded to the central package server via the `opm upload` command.\n\nOne example `dist.ini` file looks like below for OpenResty's\n[lua-resty-core](https://github.com/openresty/lua-resty-core) library:\n\n```ini\n# distribution config for opm packaging\nname = lua-resty-core\nabstract = New FFI-based Lua API for the ngx_lua module\nauthor = Yichun \"agentzh\" Zhang (agentzh)\nis_original = yes\nlicense = 2bsd\nlib_dir = lib\ndoc_dir = lib\nrepo_link = https://github.com/openresty/lua-resty-core\nmain_module = lib/resty/core/base.lua\nrequires = luajit, openresty/lua-resty-lrucache \u003e= 0.04\n```\n\nAs we can see, the `dist.ini` file is using the popular [INI file format](https://en.wikipedia.org/wiki/INI_file).\nMost of the fields in this example should be self-explanatory. For detailed documentation for the fields available\nin `dist.ini`, please check out the [File dist.ini](#file-distini) section.\n\nThe `opm build` command also reads and extracts information from the configuration file `.opmrc` under the current\nsystem user's home directory (i.e., with the file path `~/.opmrc`). If the file does not exist, `opm build` will\nautomatically generates a boilerplate file in that path. One sample `~/.opmrc` file looks like this.\n\n```ini\n# your github account name (either your github user name or github organization that you owns)\ngithub_account=agentzh\n\n# you can generate a github personal access token from the web UI: https://github.com/settings/tokens\n# IMPORTANT! you are required to assign the scopes \"user:email\" and \"read:org\" to your github token.\n# you should NOT assign any other scopes to your token due to security considerations.\ngithub_token=0123456789abcdef0123456789abcdef01234567\n\n# the opm central servers for uploading openresty packages.\nupload_server=https://opm.openresty.org\ndownload_server=https://opm.openresty.org\n```\n\nBasically, the `opm build` command just needs the `github_account` setting from this file. Other fields are needed\nby the `opm upload` command that tries to upload the packaged tarball onto the remote package server. You can either\nuse your own GitHub login name (which is `agentzh` in this example), or a GitHub organization name that you owns\n(i.e., having the `admin` permission to it).\n\nAfter `opm build` successfully generates a `.tar.gz` file under the current working directory, the author can use\nthe `opm upload` command to upload that file to the remote server. To ensure consistency, `opm upload` automatically\nruns `opm build` itself right before attempting the uploading operation. The central package server (`opm.openresty.org`\nin this case) calls the GitHub API behind the scene to validate the author's identify. Thus the author needs to\nprovide his GitHub personal access token in her `~/.opmrc` file. Only the `user:email` and `read:org` permissions\n(or `scopes` in the GitHub terms) need to be assigned to this access token.\n\n[Back to TOC](#table-of-contents)\n\nFile dist.ini\n=============\n\nThe `dist.ini` file specifies the meta data of a package and is used by `opm build`\nto generate a tarball that is ready to upload to the remote package server. This\nfile should sit at the top of the library or module source tree.\n\nThis file uses the [INI file format](https://en.wikipedia.org/wiki/INI_file). It\ncontains the following keys (or properties) in the default top-level section:\n\n[Back to TOC](#table-of-contents)\n\nname\n----\n\nSpecifies the name of the package (excluding version numbers). For example,\n\n```ini\nname = lua-resty-limit-traffic\n```\n\nThe name can only contain letters, digits, and dashes (`-`).\n\nThis key is mandatory.\n\n[Back to TOC](#table-of-contents)\n\nabstract\n--------\n\nAbstract for the current package.\n\n```ini\nabstract = New FFI-based Lua API for the ngx_lua module\n```\n\nYou can use UTF-8 characters in this field value. Invalid UTF-8 sequences, however,\nwill lead to errors in `opm build` or `opm server-build` commands.\n\nThis key is mandatory.\n\n[Back to TOC](#table-of-contents)\n\nversion\n-------\n\nVersion number for the current package.\n\nIf this key is specified, then the version number specified here will be automatically compared with\nthe version number extracted from the \"main module\" file (see the [main_module](#main_module) key for more\ndetails).\n\nExample:\n\n```ini\nversion = 1.0.2\n```\n\nSee also the [Version Number Handling](#version-number-handling) section for more details on package\nversion numbers.\n\nThis key is optional.\n\n[Back to TOC](#table-of-contents)\n\nauthor\n------\n\nSpecifies one or more authors of the libraries. For instance,\n\n```ini\nauthor = Yichun Zhang (agentzh)\n```\n\nThe names of multiple authors should\nbe separated by a comma, with optional surrounding spaces.\n\n```ini\nauthor = Yichun Zhang (agentzh), Dejiang Zhu\n```\n\nYou can use UTF-8 characters in this field value. Invalid UTF-8 sequences, however,\nwill lead to errors in `opm build` or `opm server-build` commands.\n\nThis key is mandatory.\n\n[Back to TOC](#table-of-contents)\n\nlicense\n-------\n\nSpecifies the license for the library. For example,\n\n```ini\nlicense = 3bsd\n```\n\nThis assigns the 3-clause BSD license to the current package.\n\nSpecial IDs for common code licenses are required. For now, the following IDs are supported:\n\n* `2bsd`\n\nBSD 2-Clause \"Simplified\" or \"FreeBSD\" license\n* `3bsd`\n\nBSD 3-Clause \"New\" or \"Revised\" license\n* `apache2`\n\nApache License 2.0\n* `artistic`\n\nArtistic License\n* `artistic2`\n\nArtistic License 2.0\n* `ccby`\n\nCreative Commons Attribution 4.0 International Public License\n* `ccbysa`\n\nCreative Commons Attribution-ShareAlike 4.0 International Public License\n* `ccbynd`\n\nCreative Commons Attribution-NoDerivatives 4.0 International Public License\n* `ccbync`\n\nCreative Commons Attribution-NonCommercial 4.0 International Public License\n* `ccbyncsa`\n\nCreative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License\n* `ccbyncnd`\n\nCreative Commons Attribution-NonCommercial-NoDerivatives 4.0 International Public License\n* `cddl`\n\nCommon Development and Distribution License\n* `eclipse`\n\nEclipse Public License\n* `gpl`\n\nGNU General Public License (GPL)\n* `gpl2`\n\nGNU General Public License (GPL) version 2\n* `gpl3`\n\nGNU General Public License (GPL) version 3\n* `lgpl`\n\nGNU Library or \"Lesser\" General Public License (LGPL)\n* `mit`\n\nMIT license\n* `mozilla2`\n\nMozilla Public License 2.0\n* `proprietary`\n\nProprietary\n* `public`\n\nPublic Domain\n\nIf you do need an open source license not listed above, please let us know.\n\nIt is also possible to specify multiple licenses at the same time, as in\n\n```ini\nlicense = gpl2, artistic2\n```\n\nThis specifies dual licenses: GPLv2 and Artistic 2.0.\n\nTo upload the package to the official opm package server, you must at least specify\nan open source license here.\n\nThis key is mandatory.\n\n[Back to TOC](#table-of-contents)\n\nrequires\n--------\n\nSpecifies the runtime dependencies of this package.\n\nMultiple dependencies are separated by commas, with optional surrounding spaces. As in\n\n```ini\nrequires = foo/lua-resty-bar, baz/lua-resty-blah\n```\n\nAll the dependency constraints specified in this key must be met at the same time when\nthe `opm get` or `opm build` command is run.\n\nYou can also specify version number requirements, as in\n\n```ini\nrequires = foo/lua-resty-bar \u003e= 0.3.5\n```\n\nThe version comparison operators supported are `\u003e=`, `=`, and `\u003e`. Their\nsemantics is self-explanatory.\n\nYou can also specify the following special dependency names:\n\n* `luajit`\n\nRequires the LuaJIT component in the package user's OpenResty installation (and also the package uploader's). When\nversion number constraints are specified, the version number of the LuaJIT will also be checked.\n* `nginx`\n\nRequires the NGINX component in the package user's OpenResty installation (and also the package uploader's). When\nversion number constraints are specified, the version number of the NGINX core will also be checked.\n* `openresty`\n\nThis dependency only makes sense when there is an associated version number constraint specified.\nThe version number of the package user's (and also uploader's) OpenResty installation must meet the version\nconstraint here.\n* `ngx_http_lua`\n\nRequires the ngx_http_lua_module component in the package user's OpenResty installation (and also the package uploader's).\nWhen version number constraints are specified, the version of the installed ngx_http_lua_module will also be checked.\n\nBelow is such an example:\n\n```ini\nrequires = luajit \u003e= 2.1.0, nginx \u003e= 1.11.2, ngx_http_lua = 0.10.6\n```\n\nor you can just specify a single `openresty` version constraint to cover them all in the example above:\n\n```ini\nrequires = openresty \u003e= 1.11.2.1\n```\n\nThis key is optional.\n\n[Back to TOC](#table-of-contents)\n\nrepo_link\n---------\n\nThe URL of the code repository (usually on GitHub). For example,\n\n```ini\nrepo_link = https://github.com/openresty/lua-resty-core\n```\n\nIf the repository is on GitHub, then `opm build` ensures that the name\nspecified in the `github_account` in your `~/.opmrc` file *does* match\nthe account in your GitHub repository URL. Otherwise `opm build` reports\nan error.\n\nThis key is mandatory.\n\n[Back to TOC](#table-of-contents)\n\nis_original\n-----------\n\nTakes the value `yes` or `no` to specify whether this package is an original work\n(that is, not a fork of another package of somebody else).\n\nThis key is mandatory.\n\n[Back to TOC](#table-of-contents)\n\nlib_dir\n-------\n\nSpecifies the root directory of the library files (`.lua` files, for example).\n\nYou must not use absolute directory paths or paths containing `..` as the value.\n\nDefault to `lib`.\n\nThis key is optional.\n\n[Back to TOC](#table-of-contents)\n\nexclude_files\n-------------\n\nSpecifies patterns for files to be excluded during packaging via `opm bulid`.\nUnix shell wildcards like `*` and `?` are supported.\n\nMultiple patterns should be separated by commas, with optional surrounding spaces.\n\n```ini\nexclude_files=foo*.lua, bar/baz/*/*.lua, lint_config.lua\n```\n\n[Back to TOC](#table-of-contents)\n\nmain_module\n-----------\n\nThis key specifies the PATH of the \"main module\" file of the current package.\nThe `opm build` command reads the \"main module\" file to extract the version number\nof the current package, for example.\n\n`opm build` uses simple regular expressions to find Lua code patterns like below:\n\n```lua\n_VERSION = '1.0.2'\n```\n\n```lua\nversion = \"0.5\"\n```\n\n```lua\nversion = 0.08\n```\n\nWhen this key is not specified, then `opm build` will try to find the main module\nfile automatically (which might be wrong though).\n\nYou must not use absolute file paths or paths containing `..` as the value.\n\nThis key is optional.\n\n[Back to TOC](#table-of-contents)\n\ndoc_dir\n-------\n\nSpecifies the root directory of the documentation files. Default to `lib`.\n\nYou must not use absolute directory paths or paths containing `..` as the value.\n\n`opm build` always tries to collect the documentation files in either the Markdown (`.md` or `.markdown`)\nor the POD (`.pod`) format.\n\nRegardless of the value of this `doc_dir` key, `opm build` always tries to collect\nthe following files in the current working directory (which should be the root of\nthe current package):\n\n* `README.md`, `README.markdown`, or `README.pod`\n* `COPYING`\n* `COPYRIGHT`\n* `Changes.md`, `Changes.markdown`, or `Changes.pod`\n\nYou can use UTF-8 characters in these documentation files. Other multi-byte character\nencodings must be avoided.\n\nThis key is optional.\n\n[Back to TOC](#table-of-contents)\n\nFile .opmrc\n===========\n\nThe `.opmrc` file under the current system user's home directory configures various important settings\nfor the current system user. Only library\nauthors should care about this file since commands like `opm get`, `opm search`, or `opm list` do\nnot need this file at all.\n\nLike [file dist-ini](#file-distini), this file is also in the [INI file format](https://en.wikipedia.org/wiki/INI_file).\nWhen this file is absent, the first run of the `opm build` or `opm upload` commands will automatically generate\na boilerplate file for you to fill out later yourself.\n\nThis file recognizes the following keys:\n\n[Back to TOC](#table-of-contents)\n\ngithub_account\n--------------\n\nSpecifies your GitHub account name, either your GitHub user login name or\ngithub organization that you owns.\n\nFor example, the document writer's GitHub login name is `agentzh` while he\nalso owns the GitHub organization `openresty`. So he can choose to upload\nhis packages either under the `agentzh` or `openresty` with the same GitHub\naccess token (defined via the [github_token](#github_token) key) by configuring\nthis `github_account` key.\n\nThis key is required.\n\n[Back to TOC](#table-of-contents)\n\ngithub_token\n------------\n\nSpecifies your GitHub personal access token used for package uploads.\n\nYou can generate a GitHub personal access token from the GitHub [web UI](https://github.com/settings/tokens).\n\nWhile you are generating your token on GitHub's web site, it is crucial to assign the right permissions (or `scopes`\nin GitHub's terminology) to your token. The `opm` tool chain requires that the token must contain the `user:email`\nscope. Optionally, you can also assign the `read:org` scope at the same time, which is required if you want to\nupload your OpenResty packages under an organization name that you owns.\n\nThe GitHub personal access tokens are like passwords, so be very careful when handling it. Never share it with\nthe rest of the world otherwise anybody can upload packages to the OPM package server under *your* name.\n\nDue to security considerations, the package server also rejects GitHub personal access tokens that are too permissive\n(that is, having more scopes than needed). The package server caches a sorted hash of your tokens in its own database,\nso that the server does not have to query GitHub upon subsequent uploads. Because the tokens are hashed, the package\nserver can only verifies that your token is correct but cannot recover your original token just from the database.\n\nThis key is required.\n\n[Back to TOC](#table-of-contents)\n\nupload_server\n-------------\n\nSpecifies the OPM server for uploading packages. Defaults to `https://opm.openresty.org`. It is strongly recommended\nto use `https` (which is the default) for communication privacy.\n\nThe official OPM package server is `https://opm.openresty.org`. You could, however, point this key to your own or\nany 3rd-party servers (then you are at your own risk).\n\nThis key can have a different value than [download_server](#download_server).\n\n[Back to TOC](#table-of-contents)\n\ndownload_server\n---------------\n\nSpecifies the OPM server for downloading packages. Defaults to `https://opm.openresty.org`. It is strongly recommended\nto use `https` (which is the default) for communication privacy.\n\nThe official OPM package server is `https://opm.openresty.org`. You could, however, point this key to your own or\nany 3rd-party servers (then you are at your own risk).\n\nThis key can have a different value than [upload_server](#upload_server).\n\n[Back to TOC](#table-of-contents)\n\nVersion Number Handling\n=======================\n\nOPM requires all package version numbers to only consist of digits, dots, alphabetic letters, and underscores.\nOnly the digits part are mandatory.\n\nOPM treats all version numbers as one or more integers separated by dots (`.`) or any other non-digit characters.\nVersion number comparisons are performed by comparing each integer part in the order of their appearance.\nFor example, the following version number comparisons hold true:\n\n```\n12 \u003e 10\n1.0.3 \u003e 1.0.2\n1.1.0 \u003e 1.0.9\n0.10.0 \u003e 0.9.2\n```\n\nThere can be some surprises when your version numbers look like decimal numbers, as in\n\n```\n0.1 \u003c 0.02\n```\n\nThis is because `0.1` is parsed as the integer pair `{0, 1}`, while `0.02` is parsed as\n`{0, 2}`, so the latter is greater than the former.\nTo avoid such pitfalls, always specify the decimal part of the equal length, that is,\nwriting `0.1` as `0.10`, which is of the same length as `0.02`.\n\nOPM does not support special releases like \"release candidates\" (RC) or \"developer releases\" yet.\nBut we may add such support in the future. For forward-compatibility, the package author\nshould avoid version numbers with suffixes like `_2` or `rc1`.\n\n[Back to TOC](#table-of-contents)\n\nInstallation\n============\n\nFor opm\n-------\n\n[OpenResty releases](https://openresty.org/en/download.html) since `1.11.2.2` already include and\ninstall `opm` by default. So usually you do *not* need to install `opm` yourself.\n\nIt worth noting that if you are using the official OpenResty\n[prebuilt linux packages](https://openresty.org/en/linux-packages.html), you should install the\n[openresty-opm](https://openresty.org/en/rpm-packages.html#openresty-opm) package since the\n[openresty](https://openresty.org/en/rpm-packages.html#openresty) binary package itself does not\ncontain `opm`.\n\nIf you really want to update to the latest version of\n`opm` in the code repository, then just copy the file `bin/opm` in the repository over to\n`\u003copenresty-prefix\u003e/bin/` where `\u003copenresty-prefix\u003e` is the value of the `--prefix` option of\n`./configure` while you are building your OpenResty (defaults to `/usr/local/openresty/`).\n\n```bash\n# \u003copenresty-prefix\u003e defaults to `/usr/local/openresty/`\n# unless you override it when building OpenResty yourself.\nsudo cp bin/opm \u003copenresty-prefix\u003e/bin/\n```\n\nIf you are using an older version of OpenResty that does *not* include `opm` by default, then\nyou should also create the following directories:\n\n```bash\ncd \u003copenresty-prefix\u003e\nsudo mkdir -p site/lualib site/manifest site/pod\n```\n\nNote that at least OpenResty 1.11.2.1 is needed for `opm` to work properly.\n\nTo run the `opm` tool, you just need `perl`, `tar`, and `curl` to run the `opm` tool. Ensure\nthat your perl is not too old (should be at least `5.10.1`), and your curl supports `SNI`.\n\n[Back to TOC](#table-of-contents)\n\nSecurity Considerations\n=======================\n\nThe `opm` client tool always uses HTTPS to talk to the package server, [opm.openresty.org](https://opm.openresty.org/),\nby default. Both for package uploading and package downloading, as well as other web service queries for meta data.\nAlthough it is possible for the user to manually switch to the HTTP protocol\nby editing the `download_server` and/or `upload_server` keys in her own `~/.opmrc` file.\nThe `opm` client tool also always verifies the SSL certificates of the remote OPM package server (via `curl` right now).\n\nSimilarly, the OPM package server always uses TLS to talk to remote services provided by GitHub and Mailgun.\nThese remote sites' SSL certificates are also always verified on the server side. This cannot be turned off by the user.\n\nThe OPM package server uses PostgreSQL's `pgcrypto` extension to encrypt the authors' GitHub personal access tokens\nin the database (we\ncache the tokens in our own database to speed up subsequent uploads and improve site reliability when the GitHub API is down).\nEven the server administrators cannot recover the original access tokens from the database.\nThe server also ensures that the author's personal token is not too permissive by rejecting such tokens.\n\nThe `opm` tool chain and server also always perform the MD5 checksum verification upon both the\ndownloaded and uploaded package files, to ensure data integrity when transferred over the wire.\n\n[Back to TOC](#table-of-contents)\n\nCredit\n======\n\nThe design of the `opm` tool gets various inspirations from various existing package management systems, including but not limited to,\nPerl's `cpan` and [Dist::Zilla](http://dzil.org/), RedHat's `yum`, NodeJS's `npm`, and Mac OS X's `homebrew`.\n\n[Back to TOC](#table-of-contents)\n\nTODO\n====\n\n* Add `opm reinstall` command to reinstall an already installed module (at the same version).\n* Add `opm doctor` command to check if there is any inconsistency in the current opm package installation tree.\n* Add `opm files \u003cpackage\u003e` command to list all the files in the specified package.\n* Add `opm whatprovides \u003cpackage\u003e` command to find out which package the specified file belongs to.\n* Add plugin mechanisms to `opm build` (similar to Perl's [Dist::Zilla](http://dzil.org/) packaging framework).\n* Turn opm.openresty.org into a full-blown web site similar to search.cpan.org.\n* Add support for Lua C modules and LuaJIT FFI modules with standalone C libraries.\n* Add support for 3rd-party NGINX C modules (which can be compiled as NGINX dynamic modules).\n* Add (limited) support for LuaRocks via the special name space `luarocks`, for example,\n\n```bash\nopm get luarocks/foo\n```\n\n[Back to TOC](#table-of-contents)\n\nAuthor\n======\n\nYichun Zhang (agentzh) \u003cagentzh@gmail.com\u003e, OpenResty Inc.\n\n[Back to TOC](#table-of-contents)\n\nCopyright and License\n=====================\n\nThis module is licensed under the BSD license.\n\nCopyright (C) 2016-2020, by Yichun \"agentzh\" Zhang (章亦春) \u003cagentzh@gmail.com\u003e, OpenResty Inc.\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n[Back to TOC](#table-of-contents)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fopm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenresty%2Fopm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Fopm/lists"}