From db46aa1ee3ac2215afd797fb3dca928709482c3a Mon Sep 17 00:00:00 2001 From: Olaf Alders Date: Sat, 27 Apr 2024 15:39:49 +0100 Subject: [PATCH] Tidy README --- README.md | 69 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index e422cd3e3..eb3f0bdc5 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,28 @@ -[![CircleCI](https://circleci.com/gh/metacpan/metacpan-api.svg?style=svg)](https://circleci.com/gh/metacpan/metacpan-api) +# A Web Service for the CPAN -A Web Service for the CPAN -========================== +[![CircleCI](https://circleci.com/gh/metacpan/metacpan-api.svg?style=svg)](https://circleci.com/gh/metacpan/metacpan-api) MetaCPAN aims to provide a free, open web service which provides metadata for CPAN modules. -REST API --------- +## REST API MetaCPAN is based on Elasticsearch, so it provides a RESTful interface as well -as the option to create complex queries. [The -`docs/` directory](https://github.com/metacpan/metacpan-api/blob/master/docs/API-docs.md) provides a good -starting point for REST access to MetaCPAN. +as the option to create complex queries. [The `docs/` +directory](https://github.com/metacpan/metacpan-api/blob/master/docs/API-docs.md) +provides a good starting point for REST access to MetaCPAN. -Expanding Your Author Info --------------------------- +## Expanding Your Author Info MetaCPAN allows authors to add custom metadata about themselves to the index. [Log in to MetaCPAN](https://metacpan.org/account/profile) to add more information about yourself. -Installing Your Own MetaCPAN: ---------------------------------------- +## Installing Your Own MetaCPAN -If you want to run MetaCPAN locally, we encourage you to start with [metacpan-docker](https://github.com/metacpan/metacpan-docker). -However, you may still find some info here: +If you want to run MetaCPAN locally, we encourage you to start with +[metacpan-docker](https://github.com/metacpan/metacpan-docker). However, you +may still find some info here: ## Troubleshooting Elasticsearch @@ -34,7 +31,10 @@ You can restart Elasticsearch (ES) manually if you need to troubleshoot. ```sh sudo service elasticsearch restart ``` -If you are unable to access [[http://localhost:9200]] (give it a few seconds) you should kill the Elasticsearch process and run it in foreground to see the debug output + +If you are unable to access [[http://localhost:9200]] (give it a few seconds) +you should kill the Elasticsearch process and run it in foreground to see the +debug output ```sh sudo service elasticsearch stop @@ -42,20 +42,24 @@ cd /opt/elasticsearch sudo bin/elasticsearch -f ``` -If you get a "Can't start up: not enough memory" error when trying to start Elasticsearch, you likely need to update your JRE. On Ubuntu: +If you get a "Can't start up: not enough memory" error when trying to start +Elasticsearch, you likely need to update your JRE. On Ubuntu: ```sh # fixes "not enough memory" errors sudo apt-get install openjdk-6-jre ``` -(Note: If you intend to try indexing a full MiniCPAN, you may find that Elasticsearch wants to use more open filehandles than your system allows by default. [This script](https://gist.github.com/3230962) can be used to start ES with the appropriate ulimit adjustment). +(Note: If you intend to try indexing a full MiniCPAN, you may find that +Elasticsearch wants to use more open filehandles than your system allows by +default. [This script](https://gist.github.com/3230962) can be used to start ES +with the appropriate ulimit adjustment). ## Run the test suite -The test suite accesses Elasticsearch on port 9900. -The developer VM should have a dedicated test instance running in the background already, -but if you want to run it manually: +The test suite accesses Elasticsearch on port 9900. The developer VM should +have a dedicated test instance running in the background already, but if you +want to run it manually: ```sh cd /opt/elasticsearch @@ -85,7 +89,8 @@ The test suite has to pass all tests. ./bin/run bin/metacpan release /path/to/cpan/authors/id/ ``` -You should note that you can index either your CPAN mirror or a minicpan mirror. You can even index just parts of a mirror: +You should note that you can index either your CPAN mirror or a minicpan +mirror. You can even index just parts of a mirror: ```sh ./bin/run bin/metacpan release /path/to/cpan/authors/id/{A,B} @@ -103,36 +108,42 @@ You should note that you can index either your CPAN mirror or a minicpan mirror. ./bin/run bin/metacpan author --cpan /path/to/cpan/ ``` -Note that minicpan doesn't provide the 00whois.xml file which is used to generate the index; you will have to download it manually (it is in the authors/ directory) in order to index authors. +Note that minicpan doesn't provide the 00whois.xml file which is used to +generate the index; you will have to download it manually (it is in the +authors/ directory) in order to index authors. - wget -O /path/to/cpan/authors/00whois.xml cpan.cpantesters.org/authors/00whois.xml +```bash +wget -O /path/to/cpan/authors/00whois.xml cpan.cpantesters.org/authors/00whois.xml +``` -It also doesn't include author.json files, so that data will also be missing unless you get it from somewhere else. +It also doesn't include author.json files, so that data will also be missing +unless you get it from somewhere else. ## Set Up Proxy in Front of ElasticSearch Start API server on port 5000 + ```sh ./bin/run plackup -p 5000 -r ``` -This will start a single-threaded test server. If you need extra performance, use `Starman` instead. +This will start a single-threaded test server. If you need extra performance, +use `Starman` instead. ## Notes For a full list of options: + ```sh ./bin/run bin/metacpan release --help ``` -Contributing: -------------- +## Contributing If you'd like to get involved, find us at #metacpan on irc.perl.org or open an issue on GitHub and let us know what you'd like to start working on. -IRC ---- +## IRC You can find us at #metacpan on irc.perl.org Access it via [web interface](https://chat.mibbit.com/?channel=%23metacpan&server=irc.perl.org).