Permalink
Browse files

Small documentation fixes.

  • Loading branch information...
oalders committed Aug 13, 2014
1 parent 7eec5b1 commit f53622e5f96e091ccc7718e05cc544adaaf51981
Showing with 63 additions and 63 deletions.
  1. +25 −25 FAQs.md
  2. +13 −13 HELP.md
  3. +21 −21 README.md
  4. +4 −4 README_API.md
View
50 FAQs.md
@@ -5,25 +5,25 @@ I am completely new to MetaCPAN. What material could I refer to, to get acquaint
- http://www.slideshare.net/oalders/the-metacpan-vm-for-dummies-part-one-installation
- http://www.slideshare.net/oalders/meta-cpan-vmparttwo
- www.slideshare.net/oalders/abusing-metacpan2013
- - We also maintain a 'metacpan-examples' repository so that you can try the examples out yourself. This will be cloned alongwith the other repos in the /src folder.
+ - We also maintain a 'metacpan-examples' repository so that you can try the examples out yourself. This will be cloned along with the other repos in the /src folder.
---------------------------------------------------------------------------------------------------------------------
Ran into some error you don't understand? Read on to see if it's a commonly faced error.
-1. I ran into certain permission errors while running a test(s) or command(s).
- - Make sure that you are operating as a 'vagrant user' and NOT 'metacpan'.
- - Hence, after 'vagrant ssh', do NOT do a 'sudo su metacpan'.
+1. I ran into certain permission errors while running a test or command.
+ - Make sure that you are operating as the 'vagrant' and NOT 'metacpan'.
+ - Hence, after 'vagrant ssh', do NOT do a 'sudo su metacpan'.
- Simply go to the respective folder and run the tests as the vagrant user.
2. Why do I get the info/notices during vagrant provision? Do I need to worry about them?
- Those info messages are puppet info/notices which come because MetaCPAN recently switched to puppet apply, and are basically just noise. So, the messages can be safely ignored.
-3. I always run into errors in the tidyall.t test while running the test suite. How could it be delt with?
- - Running a 'tidyall -a' command before pushing your code will help pass the test.
- - Also, 'sh git/setup.sh' command will set the pre-commit hook for you.
+3. I always run into errors in the tidyall.t test while running the test suite. How could it be dealt with?
+ - 'sh git/setup.sh' command will set a pre-commit hook for you.
+ - Running a 'tidyall -g' command before pushing your code will help pass the test.
This way the code will be tidied automatically before committing it and hence you won't have to worry about the test failing.
@@ -33,24 +33,24 @@ Ran into some error you don't understand? Read on to see if it's a commonly face
- A 'vagrant reload' also helps.
-5. I'm running into an ES error which says that the host timed out while trying to start the Elasticsearch service.
- - The best solution for this is to run ES in the foreground:
-
- ```
+5. I'm running into an ES error which says that the host timed out while trying to start the Elasticsearch service.
+ - The best solution for this is to run ES in the foreground:
+
+ ```
cd /opt/elasticsearch-0.20.2 && sudo ./bin/elasticsearch -f
```
-6. I got permission errors while doing a ''plackup' and this time the errors are related to the ScoreBoard.pm module.
- - ScoreBoard errors come when it is unable to detect it's folder present under var/tmp/scoreboard.
+6. I got permission errors while doing a 'plackup' and this time the errors are related to the ScoreBoard.pm module.
+ - ScoreBoard errors come when it is unable to detect its folder present under var/tmp/scoreboard.
- A good practice would be to AVOID using 'sudo service (metacpan-www/cpan-api) start|restart|stop' and use carton to run the daemon-control script as mentioned in the ReadMe. A plackup after this wouldn't give the error.
-7. Why does 'carton exec prove -l t' or './bin/prove t' work while the tests fail on 'prove -l t'?
+7. Why does './bin/carton exec prove -l t' or './bin/prove t' work while the tests fail on 'prove -l t'?
- Perl has a bunch of modules installed to the system (/usr/local/perlbrew/...), but not all of them, and not all of the necessary versions.
- - Carton will install the required modules (with the correct versions) into the ./local directory. So when you do 'carton exec ...' it will use the ./local directory for perl's @INC instead of the system wide directory and then run the command you specify so that it has the right modules available to it.
- - Sometimes you can get away with just installing all dependencies into one place... but if you ever have two apps that have different requirements, then you run into trouble so carton is a tool to help isolate dependencies so that each app has its own.
- - So, if you install all your dependencies into the system lib then you don't ever need to use carton, but if you use carton to install your dependencies, then you have to use carton in order to run everything.
+ - Carton will install the required modules (with the correct versions) into the ~/carton/[site] directory. So when you do './bin/carton exec ...' it will use the local directory for perl's @INC instead of the system wide directory and then run the command you specify so that it has the right modules available to it.
+ - Sometimes you can get away with just installing all dependencies into one place... but if you ever have two apps that have different requirements, then you run into trouble so Carton is a tool to help isolate dependencies so that each app has its own.
+ - So, if you install all your dependencies into the system lib then you don't ever need to use Carton, but if you use Carton to install your dependencies, then you have to use Carton in order to run everything.
8. I want to reinstantiate the base box and do a clean install. How could that be done?
@@ -59,30 +59,30 @@ Ran into some error you don't understand? Read on to see if it's a commonly face
9. I recently got a PAUSE account, but it is not reflected in my localhost:5000.
- - The authors/02authors.txt.gz needs to be updated in such a case.
- - CPAN usually takes a day or two for indexing the new PAUSE data, if you want to hack into the metacpan backend and get started faster a quick hack would be to add your PAUSE details manually to the authors/02authors.txt.gz that is downloaded by 'sh bin/partial-cpan-mirror.sh' in /home/vagrant/CPAN/...
+ - The authors/02authors.txt.gz needs to be updated in such a case.
+ - CPAN usually takes a day or two for indexing the new PAUSE data, if you want to hack into the MetaCPAN backend and get started faster, a quick hack would be to add your PAUSE details manually to the authors/02authors.txt.gz that is downloaded by 'sh bin/partial-cpan-mirror.sh' in /home/vagrant/CPAN/...
10. I want to log in as a Pause user in localhost:5000 on my machine, what steps should I follow for the same?
- - Get a PAUSE account working.
+ - Get a PAUSE account working.
- Make sure it is present in authors/02authors.txt.gz file.
- Enter your PAUSE id normally as you would for looging into metacpan.org
- It'll say that a link has been mailed to your mail id. But obviously you did not receive this mail.
- The link is present in /home/metacpan/api.metacpan.org/var/tmp/mail/new/(mail-link)
- - Simply click on the link to log into metacpan through your local machine.
+ - Simply click on the link to log into MetaCPAN through your local machine.
11. What is cpanfile.snapshot? I think it looks like a log from cpanfile, should we commit too when we make change on cpanfile?
- Essentially when carton reads cpanfile, it figures out all the exact versions of the modules it installs, and then writes that snapshot file so that next time, it can read from the snapshot file to install the exact same versions.
- Yes, the changes to both need to be committed, that is why we have added it to git
- - So, on another machine, carton will use that snapshot to determine exactly what to install whereas the cpanfile is much less strict in what it specifies, so it can lead to subtle differences on machines.
+ - So, on another machine, Carton will use that snapshot to determine exactly what to install whereas the cpanfile is much less strict in what it specifies, so it can lead to subtle differences on machines.
-12. I added some code to metacpan and pushed a few commits, but I have not made any tests to test this code.
- - It is good practice to adhere to the perl-critic rules while coding. We have included a perl-critic.t test which tests if your code goes by the basic rules of coding. This helps us set a particular standard to our metacpan code.
+12. I added some code to MetaCPAN and pushed a few commits, but I have not made any tests to test this code.
+ - It is good practice to adhere to the perl-critic rules while coding. We have included a perl-critic.t test which tests if your code goes by the basic rules of coding. This helps us set a particular standard to our metacpan code.
- Simply add the path of your new files to t/perl-critic.t so that they can be tested.
----
Point to be noted:
- - Always do a 'git pull' on all the repositories before starting off with development.
+ - Always do a 'git pull' on all the repositories before starting off with development.
- A lot of changes keep happening in the repos and so, it's always safe to have all the recent changes in your local machine.
View
26 HELP.md
@@ -3,7 +3,7 @@
## A note about tuning the VirtualBox
There is anecdotal evidence that some VirtualBox VMs consume a great deal
- of CPU time, even when idle. A metacpan VM normally consumes about 5% of
+ of CPU time, even when idle. A MetaCPAN VM normally consumes about 5% of
CPU when idle.
While everyone's setup is different, the following seems to work well (note
@@ -16,33 +16,33 @@
- Processor / 1 CPU, no execution cap
- Acceleration / Hardware Virtualization:
- [x] Enable VT-x/AMD-V
- - [ ] Enable Nested Paging
+ - [ ] Enable Nested Paging
See http://tech.shantanugoel.com/2009/07/07/virtualbox-high-cpu-usage-problem-solved.html for some discussion on this topic.
## Problems starting the VM
-- Make sure you have recent versions [Vagrant](http://www.vagrantup.com/downloads.html) (1.2.2+) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads) (4.2.12+)
+- Make sure you have recent versions of [Vagrant](http://www.vagrantup.com/downloads.html) (1.2.2+) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads) (4.2.12+)
- Open VirtualBox
- - Shutdown the box.
- - Go to 'display' options for the VM, then 'remote display' and 'enable server'
- - Then start the VM through VirtualBox and you will see a large console
+ - Shut down the box.
+ - Go to 'display' options for the VM, then 'remote display' and 'enable server'
+ - Then start the VM through VirtualBox and you will see a large console
- Sometimes the VM can enter a 'Guru Meditation' state during a 'vagrant up' command. In such a situation,
- - Force stop the VM from the terminal: VBoxManage controlvm (VM Name) poweroff
- - Go to the 'Settings' options for the VM from the Virtual Box.
- - Go to the 'System' tab, and then the 'Processors' tab. Enable the 'PAE mode' by checking the option.
- - Now do a 'vagrant up'.
+ - Force stop the VM from the terminal: VBoxManage controlvm (VM Name) poweroff
+ - Go to the 'Settings' options for the VM from the Virtual Box.
+ - Go to the 'System' tab, and then the 'Processors' tab. Enable the 'PAE mode' by checking the option.
+ - Now do a 'vagrant up'.
## Problems running a script?
- Make sure you have the right perl... run
- source /home/metacpan/.metacpanrc
+ source /home/metacpan/.metacpanrc
## Where are the log files?
- /opt/elasticsearch/logs
-- /var/www/(site)/logs
-- /home/metacpan/api.metacpan.org/var/log/
+- /var/www/[site]/logs
+- /home/metacpan/[site]/var/log/
View
@@ -12,14 +12,14 @@
- Check out this repo.
```bash
- git clone git://github.com/CPAN-API/metacpan-developer.git
+ git clone git://github.com/CPAN-API/metacpan-developer.git
```
- Set Up repositories
```bash
- cd metacpan-developer
- sh bin/init.sh
+ cd metacpan-developer
+ sh bin/init.sh
```
- Start the virtual machine (first run will download our .box disk image
@@ -34,29 +34,29 @@ might need to run this each time you start up the machine or if we have made
further changes)
```bash
- vagrant provision
+ vagrant provision
```
If you get this error when provisioning "err: Could not request certificate: Connection refused - connect(2)"
then add the following to your /etc/resolv.conf as the first nameserver:
```bash
- nameserver 8.8.8.8
+ nameserver 8.8.8.8
```
So, your /etc/resolv.conf should look something like
```bash
- domain home
- search home
- nameserver 8.8.8.8
- nameserver 10.0.2.3
+ domain home
+ search home
+ nameserver 8.8.8.8
+ nameserver 10.0.2.3
```
- Connect to the vm
```bash
- vagrant ssh
+ vagrant ssh
```
- To edit and test
@@ -99,21 +99,21 @@ So, your /etc/resolv.conf should look something like
- To connect the web front-end to your local cpan-api backend.
- At times you may have to make a few changes to the backend and reflect the same on the front end.
- For Example: Setting up a new API endpoint.
+ At times you may have to make a few changes to the backend and reflect the same on the front end.
+ For Example: Setting up a new API endpoint.
metacpan-web by default uses the hosted api i.e https://api.metacpan.org as its backend.
To configure your local cpan-api, do the following.
- In the metacpan-web repository,
- - Copy and Paste the `metacpan_web.conf` file and rename it as `metacpan_web_local.conf` that will contain:
-
- ```
- api http://127.0.0.1:5000
- api_external http://127.0.0.1:5000
- api_secure http://127.0.0.1:5000
- api_external_secure http://127.0.0.1:5000
- ```
-
+ - Copy and Paste the `metacpan_web.conf` file and rename it as `metacpan_web_local.conf` that will contain:
+
+ ```
+ api http://127.0.0.1:5000
+ api_external http://127.0.0.1:5000
+ api_secure http://127.0.0.1:5000
+ api_external_secure http://127.0.0.1:5000
+ ```
+
- This local configuration file will be loaded on top of the existing config file.
- Do a vagrant reload after this or simply follow the debug steps that will reload this file.
View
@@ -88,19 +88,19 @@ Setup everything as per the main [README](README.md)...
export MINICPAN=$HOME/CPAN
# Easy and quick
- ./bin/metacpan mapping --delete
+ ./bin/carton ./bin/metacpan mapping --delete
# Release processing will be the most time consuming
# Around 10-15 distros a minute, or 40-50 hours for a full load
# Use the --age parameter for partial loading (like --age 4320 for six months)
- ./bin/metacpan release $MINICPAN/authors/id/
+ ./bin/carton ./bin/metacpan release $MINICPAN/authors/id/
# Around 60 distros a minute
# Large/weird files (ie: Alien::Debian::Apt::PM) might timeout ES; re-run it if it chokes
- ./bin/metacpan latest --cpan $MINICPAN
+ ./bin/carton ./bin/metacpan latest --cpan $MINICPAN
# Easy and quick
- ./bin/metacpan author --cpan $MINICPAN
+ ./bin/carton ./bin/metacpan author --cpan $MINICPAN
```
- Running the API test suite

0 comments on commit f53622e

Please sign in to comment.