Merge branch '2757-source-install-upgrade-docs' into release-v1.8

doc/install-from-source.rst

@@ -221,3 +221,86 @@ they all pass. See :doc:`test`.
 
 You can now proceed to :doc:`post-installation` which covers creating a CKAN
 sysadmin account and deploying CKAN with Apache.
+
+Upgrading a source install
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before upgrading your version of CKAN you should check that any custom
+templates or extensions you're using work with the new version of CKAN. For
+example, you could install the new version of CKAN in a new virtual environment
+and use that to test your templates and extensions.
+
+You should also read the `CKAN Changelog <https://github.com/okfn/ckan/blob/master/CHANGELOG.txt>`_
+to see if there are any extra notes to be aware of when upgrading to the new
+version.
+
+1. Backup your CKAN database using the ``ckan db dump`` command, for example::
+
+    paster --plugin=ckan db dump --config=/path/to/your/ckan.ini my_ckan_database.pg_dump
+
+   This will create a file called ``my_ckan_database.pg_dump``, if something
+   goes wrong with the CKAN upgrade you can use this file to restore the
+   database to its pre-upgrade state. See :ref:`dumping and loading` for
+   details of the `ckan db dump` and `ckan db load` commands.
+
+2. Checkout the new CKAN version from git, for example::
+
+    cd pyenv/src/ckan
+    git fetch
+    git checkout release-v1.8.1
+
+   If you have any CKAN extensions installed from source, you may need to
+   checkout newer versions of the extensions at this point as well. Refer to
+   the documentation for each extension.
+
+3. Update CKAN's dependencies. Make sure that your CKAN virtual environment
+   is active, then run this command::
+
+     pip install --upgrade -r /path/to/your/pyenv/ckan/ckan/pip-requirements.txt
+
+4. If you are upgrading to a new major version of CKAN (for example if you are
+   upgrading to CKAN 1.7, 1.8 or 1.9, etc.), update your CKAN database's schema
+   using the ``ckan db upgrade`` command.
+
+    .. warning ::
+
+        To avoid problems during the database upgrade, comment out any
+        plugins that you have enabled on your ini file. You can uncomment
+        them back when the upgrade finishes.
+
+   For example::
+
+    paster --plugin=ckan db upgrade --config=/path/to/your/ckan.ini
+
+   If you are just upgrading to a minor version of CKAN (for example upgrading
+   from version 1.8 to 1.8.1) then it should not be necessary to upgrade your
+   database.
+
+   See :ref:`upgrade migration` for details of the ``ckan db upgrade`` command.
+
+5. If CKAN's Solr schema version has changed between the CKAN versions you're
+   upgrading from and to, then you need to update your solr schema symlink
+   (Check the CHANGELOG to see if it necessary to update the schema, otherwise
+   you can skip this step).
+
+   When :ref:`setting up solr` you created a symlink
+   ``/etc/solr/conf/schema.xml`` linking to a CKAN Solr schema file such as
+   ``/path/to/your/pyenv/ckan/ckan/config/solr/schema-1.4.xml``. This symlink
+   should be updated to point to the latest schema file in
+   ``/path/to/your/pyenv/ckan/ckan/config/solr/``, if it doesn't already.
+
+   After updating the symlink, you must rebuild your search index by running
+   the ``ckan search-index rebuild`` command, for example::
+
+    paster --plugin=ckan search-index rebuild --config=/path/to/your/ckan.ini
+
+   See :ref:`rebuild search index` for details of the
+   ``ckan search-index rebuild`` command.
+
+6. Finally, restart your web server. For example if you have deployed CKAN
+   using the Apache web server on Ubuntu linux, run this command::
+
+    sudo service apache2 restart
+
+7. You're done! You should now be able to visit your CKAN website in your web
+   browser and see that it's now running the new version of CKAN.

doc/paster.rst

@@ -184,6 +184,8 @@ You can delete everything in the CKAN database, including the tables, to start f
 
 The next logical step from this point is to do a "db init" step before starting CKAN again.
 
+.. _dumping and loading:
+
 Dumping and Loading databases to/from a file
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -202,6 +204,8 @@ To load it in again, you first have to clean the database of existing data (be c
 
 The pg_dump file notes which PostgreSQL user 'owns' the data on the server. Because the PostgreSQL user (by default) is identified as the current Linux user, and this is setup to be ``ckanINSTANCE`` where ``INSTANCE`` is the name of the CKAN instance. This means if you want to restore the pg_dump as another CKAN instance name (often needed if you move it to another server) then you will need to change the database owner - see :doc:`howto-editing-database-ownership`.
 
+.. _upgrade migration:
+
 Upgrade migration
 ~~~~~~~~~~~~~~~~~
 
@@ -248,6 +252,7 @@ This important command gives you fine-grained control over CKAN permissions, by
 
 The ``roles`` command has its own section: see :doc:`authorization`.
 
+.. _rebuild search index:
 
 search-index: Rebuild search index
 ----------------------------------

doc/solr-setup.rst

@@ -1,3 +1,5 @@
+.. _setting up solr:
+
 ===============
 Setting up Solr
 ===============