From 876ac911e87612d4154b9aaa168304d4a4231b1a Mon Sep 17 00:00:00 2001 From: Mike Pirog Date: Mon, 3 Dec 2012 17:07:01 -0800 Subject: [PATCH] upate documentation --- CHANGELOG.txt | 11 ++++ INSTALL.txt | 160 ++++++-------------------------------------------- PANTHEON.txt | 91 ++++++++++++++++++++++++++++ README.txt | 1 + SOLR.txt | 27 +++++++++ XDEBUG.txt | 33 +++++++++++ 6 files changed, 182 insertions(+), 141 deletions(-) create mode 100644 PANTHEON.txt create mode 100644 SOLR.txt create mode 100644 XDEBUG.txt diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 582525c..e2bf137 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -2,6 +2,17 @@ Changelog ====================== +Version 1.0-rc5 +- Added docs for SOLR, XDEBUG +- Improved documentation +- Bumped APC shm size +- Added webgrind and conditional profiling with xdebug (grind.kala) +- Updated solr to work with drupal's search_api_solr +- Corrected permission error with private files directory +- Updated rsync command +- Excluding less directory from files sync +- Remove home/drush samba shares in prep for dashboard + Version 1.0-rc4 - Fixed image cache files not generating - Fixed NUCLEAR drush crush bug diff --git a/INSTALL.txt b/INSTALL.txt index 137b458..8928cf8 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -5,21 +5,14 @@ Installation PRE-INSTALLATION CHECKS -You can install Kalabox manually as this allows for additional configuration and -customization or you can download our premade box and get up -and running right away! However before you do either there are a couple of +Kalabox currently shops as a premade Virtual Box image. This way you can get up +and running right away! However before you do this there are a couple of steps you need to do first. 1. Install Virtual Box (https://www.virtualbox.org/wiki/Downloads) 2. Add the following entry to the /etc/hosts* file on your computer. - 192.168.56.101 kala KALABOXHOSTNAME php.kala - - If you are using a pre made box KALABOXHOSTNAME = kalabox, if you are - installing manually you should replace KALABOXHOSTNAME with whatever you plan - on entering as a hostname during the installation of Ubuntu 12.04 Server. - Do notuse the hostname kalabox as this is reserved for our premade box. - + 192.168.56.101 kala kalabox php.kala grind.kala * On Windows XP this is located at c:\WINDOWS\system32\drivers\etc\hosts 3. Make sure you have a VBOXNET network adapter in your Virtual Box. @@ -31,18 +24,10 @@ adapter is set to 192.168.56.1. IMPORTING YOUR VB APPLIANCE -Manual Install -============== -If you wish to install manually you can start by downloading our blank Kalabox at -http://files.kalamuna.com/blankbox.tar.gz - -You will also need to download the 64 bit version of Ubuntu 12.04 Server at -http://www.ubuntu.com/download/server. - -Premade Install +Download =============== -If you wish to install our pre made Kalabox you can download that at. -http://files.kalamuna.com/kalabox1rc4.tar.gz +If you wish to install our pre made Kalabox you can download it at: +http://files.kalamuna.com/kalabox1rc5.tar.gz Import your Box ================ @@ -50,35 +35,12 @@ In Virtual Box go to File -> Import Appliance and select the Kalabox that you downloaded. If you installed a pre made Kalabox all you need to do is start the box, login with user:kala, password:box and you will be good to go! -Please also check the "Post Installation Setup + Tips & Tricks" and -"Working with Pantheon" sections below. - -If you were more adventurous and installed the blank box please continue reading! - -SETTING UP YOUR SERVER - -1. Install Ubuntu 12.04 LTS Server* - - * Start your blank box and select the Ubuntu image you downloaded. - * Run through the installation normally but make sure you select eth0 as - your primary network adapter and do not select any of the packages such as - SSH or LAMP when it asks you at the end. - * After installation load up your box and login! - * Some machines may throw a kernal error. If this happens you should check your - machine's settings -> System -> Processor and check "Enable PAE/NX". - -2. Run the following commands once you have logged in: - - sudo apt-get update - sudo apt-get upgrade - sudo apt-get install puppet - sudo puppet agent --verbose --test --pluginsync --server kalabox.kalamuna.com - -That should be it! Your Kalabox should be ready to go! -Please see below for some useful tips! +Please also check the "Post Installation Setup + Tips & Tricks" below and +the other documentation that comes with the download. Post Installation Setup + Tips & Tricks ====================== + USING SSH Once you have completed the setup we recommend that you minimize VB and the @@ -86,113 +48,29 @@ VB Terminal in favor of using your HOST's terminal. This allows for a more authenticate experience as it relates to development. Open a terminal in your host and type - ssh USERNAME@kala + ssh kala@kala -This will connect you to your Kalabox. Your will use the username you set up -during installation of Ubuntu 12.04 LTS Server. If you installed a pre made box -then your user will be "kala" and your password will be "box." +This will connect you to your Kalabox. Your user will be "kala" and your password +will be "box." ACCESSING YOUR WEBROOT/DRUSH/HOME -You may want to edit your code using an IDE on your HOST, download your Pantheon -aliases or add custom drush commands. Check the network on your HOST and you -should see three shares for your vbox: +You may want to edit your code using an IDE on your HOST. Check the network on your HOST +and you should see a share for your vbox: 1. WWW <- Your Webroot - 2. DRUSH <- Your drush library - 3. HOME <- Your home folder If you don't see them you can try connecting to smb://kala. In MaxOSX you can do this by going to Finder -> Go -> Connect to Server. In Ubuntu 12.04 the shares are mounted in ~/.gvfs. - - -Working with Pantheon -====================== -SITE ALIASES - -The first step to working with Pantheon is to get your site aliases. These are -available for download on your Pantheon account page. You will want to open up -your HOME network share and put them in the .drush folder. You can verify that -they are in there by running "drush sa" on your Kalabox. - -SSH KEYS - -You are also going to want to make sure you add your Kalabox ssh public key to -pantheon. Kalabox automatically generates these keys for you on installation. -You can find the public key in ~/.ssh/id_rsa.pub. You may be able to open it by -going to the HOME network share on your host or you can run the following command -on your Kalabox: - - cat ~/.ssh/id_rsa.pub - -Just copy and paste the output into Pantheon. If you are prompted for a password -try rebooting your Kalabox. If this still doesn't work try running the following -command - - ssh -v -i ~/.ssh/id_rsa git@code.getpantheon.com - - -DRUSH - -Kalabox ships with 8 custom drush commands designed specifically for Pantheon -and Kalabox. They are useless without Pantheon's site alias file. - -These commands only work with your dev environments. You will use the same -naming convention as your pantheon aliases (PANTHEON.SITENAME.ENV) but you will -omit the @. You are using the alias name as an argument, not as an alias. -Here are the commands. - - 1. drush kala - - Will show helpful info - - 2. drush code pantheon.SITENAME.dev - - Will either git clone or git pull from your pantheon codebase to your - Kalabox at /var/www/SITENAME - - 3. drush data pantheon.SITENAME.dev - - Will either download and import from your pantheon database to your - Kalabox at kala:SITENAME_kala - - 4. drush files pantheon.SITENAME.dev - - Will sync your pantheon files to your Kalabox at - /var/www/SITENAME/sites/default/files - - 5. drush vhost pantheon.SITENAME.dev - - Will build and enable a nginx vhost file of your pantheon site on your - Kalabox at SITENAME.kala - - 6. drush build pantheon.SITENAME.dev - - Will completely build your pantheon site on your Kalabox, this will - edit settings.php and set up a vhost. After running this command and - adding your server name to your hosts /etc/hosts file you should be - able to browse to the site. - - 7. drush krefresh pantheon.SITENAME.dev - - Will refresh the code, database and files on your Kalabox from your - pantheon site - - 8. drush crush pantheon.SITENAME.dev - - Will completely remove pantheon.SITENAME.dev from your Kalabox. - -UPDATING YOUR HOST HOSTS FILE - -Remember that the Kalabox does not automatically update the /etc/hosts file on -your HOST so you will have to add the following line manually. +GITCONFIG - "192.168.56.101 SITENAME.kala" +You should also override the default gitconfig directives with your name and email. +From kalabox run: -You should now be able to navigate to SITENAME.kala in your browser and get to -your site! +git config --global user.name "YOUR NAME" +git config --global user.email user@example.com ################################################################################ diff --git a/PANTHEON.txt b/PANTHEON.txt new file mode 100644 index 0000000..4d09c35 --- /dev/null +++ b/PANTHEON.txt @@ -0,0 +1,91 @@ +################################################################################ + +Working with Pantheon +====================== +SITE ALIASES + +The first step to working with Pantheon is to get your site aliases. These are +available for download on your Pantheon account page. You will need to put the +downloaded file into ~/.drush/ on your Kalabox.. You can verify that they are +functioning correctly by running "drush sa" on your Kalabox. + +SSH KEYS + +You are also going to want to make sure you add your Kalabox ssh public key to +pantheon. Kalabox automatically generates these keys for you on installation. +You can find the public key in ~/.ssh/id_rsa.pub. You may be able to open it by +going to the HOME network share on your host or you can run the following command +on your Kalabox: + + cat ~/.ssh/id_rsa.pub + +Just copy and paste the output into Pantheon. If you are prompted for a password +try rebooting your Kalabox. If this still doesn't work try running the following +command + + ssh -v -i ~/.ssh/id_rsa git@code.getpantheon.com + + +DRUSH + +Kalabox ships with 8 custom drush commands designed specifically for Pantheon +and Kalabox. They are useless without Pantheon's site alias file. + +These commands only work with your dev environments. You will use the same +naming convention as your pantheon aliases (PANTHEON.SITENAME.ENV) but you will +omit the @. You are using the alias name as an argument, not as an alias. +Here are the commands. + + 1. drush build pantheon.SITENAME.dev + + Will completely build your pantheon site on your Kalabox, this will + edit settings.php and set up a vhost. After running this command and + adding your server name to your hosts /etc/hosts file you should be + able to browse to the site. + + 2. drush krefresh pantheon.SITENAME.dev + + Will refresh the code, database and files on your Kalabox from your + pantheon site + + 3. drush crush pantheon.SITENAME.dev + + Will completely remove pantheon.SITENAME.dev from your Kalabox. + + 4. drush kala + + Will show helpful info + + 5. drush code pantheon.SITENAME.dev + + Will either git clone or git pull from your pantheon codebase to your + Kalabox at /var/www/SITENAME + + 6. drush data pantheon.SITENAME.dev + + Will either download and import from your pantheon database to your + Kalabox at kala:SITENAME_kala + + 7. drush files pantheon.SITENAME.dev + + Will sync your pantheon files to your Kalabox at + /var/www/SITENAME/sites/default/files + + 8. drush vhost pantheon.SITENAME.dev + + Will build and enable a nginx vhost file of your pantheon site on your + Kalabox at SITENAME.kala + +UPDATING YOUR HOST HOSTS FILE + +Remember that the Kalabox does not automatically update the /etc/hosts file on +your HOST so you will have to add the following line manually. + + "192.168.56.101 SITENAME.kala" + +You should now be able to navigate to SITENAME.kala in your browser and get to +your site! + +################################################################################ + +(C) 2012 Kalamuna LLC diff --git a/README.txt b/README.txt index 3358cc3..058813c 100644 --- a/README.txt +++ b/README.txt @@ -18,6 +18,7 @@ experience. 8. drush (with custom commands for Pantheon integration) 9. PHPMyAdmin 10. samba (to expose your webroot, drush and home to your VB host) +11. webgrind (for profiling) Kalabox is a local server environment only and is not meant to be run as a production server. diff --git a/SOLR.txt b/SOLR.txt new file mode 100644 index 0000000..b82ab34 --- /dev/null +++ b/SOLR.txt @@ -0,0 +1,27 @@ +################################################################################ + +Working with Solr +====================== + +Kalabox ships with Solr running inside of Tomcat6. However, there are a couple +of caveats to working with Solr locally. + + 1. Tomcat is using port 8983 instead of 8080 + + 2. You may have to use kala as your servername instead of localhost. + + 3. The solr server is built with search_api_solr in mind. It has not + been tested with other Drupal Solr modules. For best results we + recommend you use this patched version of search_api_solr: + http://files.kalamuna.com/search_api_solr.tar.gz + + 4. If you are downloading a Pantheon site that uses Pantheon's Solr + infrastruture you are going to need to disable the pantheon_apachesolr + module when you are doign local development. + + 5. You may have to regenerate your index locally. + + +################################################################################ + +(C) 2012 Kalamuna LLC diff --git a/XDEBUG.txt b/XDEBUG.txt new file mode 100644 index 0000000..3f6f27b --- /dev/null +++ b/XDEBUG.txt @@ -0,0 +1,33 @@ +################################################################################ + +Working with Xdebug +====================== + +Kalabox ships with xdebug for both debugging and profiling. + +DEBUGGING + +For debugging we recommend you use an IDE on your host OS such as netbeans or +eclipse. The xdebug setup should already be done on the Kalabox end so you should +only need to set up your IDE. + +Here is some useful documentation to help: +http://brianfisher.name/content/drupal-development-environment-os-x-mamp-pro-eclipse-xdebug-and-drush +http://wiki.netbeans.org/HowToConfigureXDebug + +PROFILING + +For profiling we recommend you use the webgrind client which comes preconfigured +with your Kalabox and is located at grind.kala. + +Profiling on every page has a performance impact so you must trigger what pages +you want to profile. You can do this manually by appending ?XDEBUG_PROFILE to +the URL (see http://xdebug.org/docs/profiler for more detail) and then +checking webgrind. + +Many broswers also offer tools/plugins to turn profiling on and off. +https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc + +################################################################################ + +(C) 2012 Kalamuna LLC