Edit README.md

metacpan · Aug 11, 2014 · ed24738 · ed24738
1 parent 1db6059
commit ed24738
Showing 1 changed file with 91 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -25,8 +25,97 @@ information about yourself.
 Installing Your Own MetaCPAN:
 ---------------------------------------
 
-See the [installation](https://github.com/CPAN-API/cpan-api/wiki/Installation)
-page in the wiki to start playing with your own MetaCPAN installation.
+If you want to run MetaCPAN locally, we encourage you to start with a VM: [Metacpan Developer VM](https://github.com/CPAN-API/metacpan-developer)
+However, you may still find some info on this page to be of use when troubleshooting your VM.
+
+## Troubleshooting ElasticSearch
+
+You can start ElasticSearch (ES) manually if you need to troubleshoot.
+```sh
+cd /opt/elasticsearch-0.20.2
+sudo bin/elasticsearch
+```
+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
+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:
+```sh
+# fixes "not enough memory" errors
+sudo apt-get install openjdk-6-jre
+```
+(Note: If you intend to try indexing a full mini-cpan, 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:
+```sh
+bin/elasticsearch -f -Des.http.port=9900 -Des.cluster.name=testing
+```
+Then run the test suite:
+```sh
+cd /home/metacpan/api.metacpan.org
+./bin/prove t
+```
+The test suite has to pass all tests.
+
+## Create the ElasticSearch Index
+
+```sh
+./bin/metacpan mapping --delete
+```
+
+`--delete` will drop all indices first to clear the index from test data.
+
+## Begin Indexing Your Modules
+
+```sh
+./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:
+```sh
+./bin/metacpan release /path/to/cpan/authors/id/{A,B}
+```
+
+## Tag the Latest Releases
+
+```sh
+./bin/metacpan latest --cpan /path/to/cpan/
+```
+
+## Index Author Data
+
+```sh
+./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.
+
+    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.
+
+## Set Up Proxy in Front of ElasticSearch
+
+Start API server on port 5000
+```sh
+./bin/carton exec plackup -p 5000 -r
+```
+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/metacpan release --help
+```
+
+EV may seem to take forever to install because the test suite hangs, so you may have to install it without first running the test suite:
+```sh
+cpanm --notest EV
+```
 
 Contributing:
 -------------