fleshing out the Upgrade doc, and modified the references to Cheeseshop in the Install doc

docs/installation.rst

@@ -1,129 +1,129 b''
 .. _installation:
 
 ============
 Installation
 ============
 
 ``RhodeCode`` is written entirely in Python. Before posting any issues make 
 sure, your not missing any system libraries and using right version of 
 libraries required by RhodeCode. There's also restriction in terms of mercurial
 clients. Minimal version of hg client known working fine with RhodeCode is
 **1.6**. If you're using older client, please upgrade.
 
 
-Installing RhodeCode from Cheese Shop
--------------------------------------
+Installing RhodeCode from PyPI (aka "Cheeseshop")
+-------------------------------------------------
 
 Rhodecode requires python version 2.5 or higher.
 
 The easiest way to install ``rhodecode`` is to run::
 
     easy_install rhodecode
 
 Or::
 
     pip install rhodecode
 
 If you prefer to install RhodeCode manually simply grab latest release from
 http://pypi.python.org/pypi/RhodeCode, decompress the archive and run::
 
     python setup.py install
 
 Step by step installation example for Windows
 ---------------------------------------------
 
 :ref:`installation_win`
 
 
 Step by step installation example for Linux
 -------------------------------------------
 
 
 For installing RhodeCode i highly recommend using separate virtualenv_. This
 way many required by RhodeCode libraries will remain sandboxed from your main
 python and making things less problematic when doing system python updates. 
 
 - Assuming you have installed virtualenv_ create a new virtual environment 
   using virtualenv command:: 
 
     virtualenv --no-site-packages /opt/rhodecode-venv
 
 
 .. note:: Using ``--no-site-packages`` when generating your
    virtualenv is **very important**. This flag provides the necessary
    isolation for running the set of packages required by
    RhodeCode.  If you do not specify ``--no-site-packages``,
    it's possible that RhodeCode will not install properly into
    the virtualenv, or, even if it does, may not run properly,
    depending on the packages you've already got installed into your
    Python's "main" site-packages dir.
 
 
 - this will install new virtualenv_ into `/opt/rhodecode-venv`. 
 - Activate the virtualenv_ by running::
 
     source /opt/rhodecode-venv/bin/activate
 
 .. note:: If you're using UNIX, *do not* use ``sudo`` to run the
    ``virtualenv`` script.  It's perfectly acceptable (and desirable)
    to create a virtualenv as a normal user.
      
 - Make a folder for rhodecode data files, and configuration somewhere on the 
   filesystem. For example::
 
     mkdir /opt/rhodecode
   
     
 - Go into the created directory run this command to install rhodecode::
 
     easy_install rhodecode
   
   or::
  
     pip install rhodecode 
 
 - This will install rhodecode together with pylons and all other required 
   python libraries into activated virtualenv
 
 Requirements for Celery (optional)
 ----------------------------------
 
 In order to gain maximum performance
 there are some third-party you must install. When RhodeCode is used 
 together with celery you have to install some kind of message broker,
 recommended one is rabbitmq_ to make the async tasks work.
 
 Of course RhodeCode works in sync mode also and then you do not have to install
 any third party applications. However, using Celery_ will give you a large 
 speed improvement when using many big repositories. If you plan to use 
 RhodeCode for say 7 to 10 repositories, RhodeCode will perform perfectly well 
 without celery running.
    
 If you make the decision to run RhodeCode with celery make sure you run 
 celeryd using paster and message broker together with the application. 
 
 .. note::
    Installing message broker and using celery is optional, RhodeCode will
    work perfectly fine without them.
 
 
 **Message Broker** 
 
 - preferred is `RabbitMq <http://www.rabbitmq.com/>`_
 - A possible alternative is `Redis <http://code.google.com/p/redis/>`_
 
 For installation instructions you can visit: 
 http://ask.github.com/celery/getting-started/index.html.
 This is a very nice tutorial on how to start using celery_ with rabbitmq_
 
 
 You can now proceed to :ref:`setup`
 -----------------------------------
 
 
 
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv  
 .. _python: http://www.python.org/
 .. _mercurial: http://mercurial.selenic.com/
 .. _celery: http://celeryproject.org/
-.. _rabbitmq: http://www.rabbitmq.com/
  No newline at end of file
+.. _rabbitmq: http://www.rabbitmq.com/

docs/upgrade.rst

@@ -1,58 +1,99 b''
 .. _upgrade:
 
 =======
 Upgrade
 =======
 
-Upgrading from Cheese Shop
---------------------------
+Upgrading from PyPI (aka "Cheeseshop")
+---------------------------------------
 
 .. note::
-   Firstly, it is recommended that you **always** perform a database backup 
-   before doing an upgrade.
+   Firstly, it is recommended that you **always** perform a database and 
+   configuration backup before doing an upgrade.
+   
+   (These directions will use '{version}' to note that this is the version of 
+   Rhodecode that these files were used with.  If backing up your RhodeCode 
+   instance from version 1.3.6 to 1.4.0, the ``production.ini`` file would be 
+   backed up to ``production.ini.1-3-6``.)
+
+
+If using a sqlite database, stop the Rhodecode process/daemon/service, and
+then make a copy of the database file::
+
+ service rhodecode stop
+ cp rhodecode.db rhodecode.db.{version}
+
 
-The easiest way to upgrade ``rhodecode`` is to run::
+Back up your configuration file::
+
+ cp production.ini production.ini.{version}
+
+
+Ensure that you are using the Python Virtual Environment that you'd originally
+installed Rhodecode in::
+
+ pip freeze
+
+will list all packages installed in the current environment.  If Rhodecode 
+isn't listed, change virtual environments to your venv location::
+
+ source /opt/rhodecode-venv/bin/activate
+
+
+Once you have verified the environment you can upgrade ``Rhodecode`` with::
 
  easy_install -U rhodecode
 
 Or::
 
  pip install --upgrade rhodecode
 
 
-Then make sure you run the following command from the installation directory::
+Then run the following command from the installation directory::
  
  paster make-config RhodeCode production.ini
  
 This will display any changes made by the new version of RhodeCode to your
-current configuration. It will try to perform an automerge. It's always better
-to make a backup of your configuration file before hand and re check the 
-content after the automerge.
+current configuration. It will try to perform an automerge. It's recommended 
+that you re-check the content after the automerge.
 
 .. note::
    Please always make sure your .ini files are up to date. Often errors are
    caused by missing params added in new versions.
 
 
 It is also recommended that you rebuild the whoosh index after upgrading since 
 the new whoosh version could introduce some incompatible index changes. Please
 Read the changelog to see if there were any changes to whoosh.
 
 
 The final step is to upgrade the database. To do this simply run::
 
-    paster upgrade-db production.ini
+ paster upgrade-db production.ini
  
 This will upgrade the schema and update some of the defaults in the database,
 and will always recheck the settings of the application, if there are no new 
 options that need to be set.
 
+You may find it helpful to clear out your log file so that new errors are 
+readily apparent::
+
+ echo > rhodecode.log
+
+Once that is complete, you may now start your upgraded Rhodecode Instance::
+
+ service rhodecode start
+
+Or::
+
+ paster serve /var/www/rhodecode/production.ini
+
 .. note::
    If you're using Celery, make sure you restart all instances of it after
    upgrade.
 
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv  
 .. _python: http://www.python.org/
 .. _mercurial: http://mercurial.selenic.com/
 .. _celery: http://celeryproject.org/
-.. _rabbitmq: http://www.rabbitmq.com/
  No newline at end of file
+.. _rabbitmq: http://www.rabbitmq.com/