Quick start
-----------

To set up a development environment quickly, you can install the Virtualenv
package (https://pypi.python.org/pypi/virtualenv) and then run

    python quickstart.py

This will create a virtualenv under deploy/env and download, use easy_install
to get correct versions of prerequisites from the Internet, and finally run the
initial database setup.


Prerequisites
-------------

Please ensure these Python packages are available on your server:

*   Django, http://djangoproject.com: ``pip install "Django>=1.4,<1.5"`

*   Pygments, http://pygments.org: ``pip install Pygments``

    We used version 1.4 during development; earlier versions may also work.

*   South, http://south.aeracode.org/: ``pip install South``

    We used version 0.7.3 during development; earlier versions may also work.

*   Sphinx, http://sphinx.pocoo.org: ``pip install Sphinx``

    We used version 1.1 during development because it handles MathJax.

    Note that the Sphinx requirement might seem to be a bit of an overkill
    for comment compiling. We use it though because it handles math nicely
    (a requirement for scientific commenting), and formats all manner of
    bullets, paragraphs, tt-text, etc. ``rst2html`` from ``docutils`` might
    be a better, lightweight substitute in the future.

*   Haystack search, http://haystacksearch.org: ``pip install django-haystack``

    We used versions 1.2.x during development.

    You can edit the ``search_settings.py`` file under ``deploy`` to customize
    the search options.

    We use either the Xapian or the Whoosh backend with Haystack:

    *   Whoosh: ``pip install Whoosh``

    *   For Xapian, see the installation instructions at
        http://django-haystack.readthedocs.org/en/latest/installing_search_engines.html

        Installation in a hosted environment will require more work.

        (We use Xapian version 1.2.6 on our dev and production servers)

        After installing Xapian, also install xapian-haystack:

        *   ``pip install xapian-haystack``

*   User registration, https://bitbucket.org/ubernostrum/django-registration/: ``pip install django-registration``

*   Python Imaging Library (for screenshot handling): ``pip install PIL``

*   Mercurial: http://mercurial.selenic.com

Not required yet (might be as we add more functionality to the site):

*   ``pip install python-openid``


Installation
--------------

#.  Cloning the SciPy Central code repository:

    ``git clone https://github.com/scipy/SciPyCentral.git``

#.  Ensure the following Django settings are in your ``settings.py`` file:

    *   ``CSRF_FAILURE_VIEW = 'scipy_central.pages.views.csrf_failure'``
    *   ``ROOT_URLCONF = 'deploy.urls'``
    *   ``INSTALLED_APPS`` contains these apps:

        *   ``'django.contrib.auth'``
        *   ``'django.contrib.contenttypes'``
        *   ``'django.contrib.sessions'``
        *   ``'django.contrib.sites'``
        *   ``'django.contrib.messages'``
        *   ``'django.contrib.staticfiles'``
        *   ``'django.contrib.admin'``
        *   ``'django.contrib.admindocs'``
        *   ``'django.contrib.humanize'``
        *   ``'haystack'``
        *   ``'registration'``
        *   ``'south'``
        *   ``'widget_tweaks'``
        *   ``'scipy_central.filestorage'``
        *   ``'scipy_central.pages'``
        *   ``'scipy_central.person'``
        *   ``'scipy_central.submission'``
        *   ``'scipy_central.tagging'``
        *   ``'scipy_central.screenshot'``
        *   ``'scipy_central.pagehit'``

    *   ``AUTH_PROFILE_MODULE = 'person.UserProfile'``
    *   ``ACCOUNT_ACTIVATION_DAYS = 7``
    *   ``REGISTRATION_OPEN = True``
    *   ``LOGIN_URL = '/user/login/'``
    *   ``SPC = { ... }``: see which key-value pairs are required by examing
        the code in the ``settings.py`` file that is part of the SciPy
        Central code repository.
    *   ``JQUERY_URL = '...'``
    *   ``JQUERYUI_URL = '...'``
    *   ``JQUERYUI_CSS = '...'``
    *   ``ANALYTICS_SNIPPET = '...'``
    *   ``LOGGING = {...}``: you need a logger called ``scipycentral``, see
        more information at http://docs.djangoproject.com/en/dev/topics/logging
        and also see the ``settings.py`` file that is part of the SciPy
        Central code repository.

#.	``./manage.py syncdb``
#.  ``./manage.py migrate``          # to run the ``south`` db migrations
#.	``./manage.py loaddata sample``  # to load licenses, tags and other data
#.  ``./manage.py rebuild_index``    # to rebuild the Haystack search index
#.  or ``./manage.py update_index``


Backup and restore
------------------

There are 4 components to backup:

    #.  Database: use ``deploy/backup_site.py``
    #.  Repositories: use ``rsync`` and mirror ``SPC['storage_dir']``
        directory that you set in ``settings.py``
    #.  Raw image files: rsync the ``SPC['raw_image_dir']``
    #.  Resized images: rsync the ``SPC['resized_image_dir']``

To restore:

    #.  Delete your existing database.

    #.  Run: ``./manage.py syncdb`` to create the empty tables in the database.

    #.  ``./manage.py migrate`` to run the ``south`` db migrations

    #.  ``./manage.py reset contenttypes`` to remove the ``contenttypes``
        objects created by ``syncdb``, which will inevitibly clash with those
        restored from the database dump (in the next step). See
        http://stackoverflow.com/questions/853796/problems-with-contenttypes-when-loading-a-fixture-in-django

    #.  ``./manage.py loaddata backup-YYYY-MM-DD-HH-MM-SS.json``

        which restores the json database dump created by ``backup_site.py`` in
        step 1 of the backup procedure.

    #.  Do a full mirror of the rsynced repositories to your new
        ``SPC['storage_dir']`` location. This storage contains hidden
        directories (.hg or .git directories).

    #.  Similarly, restore the mirror of the resized images (the raw images
        may optionally be restored).




Attribution
-----------

Code from other BSD-licensed applications has been used in this project, and
attributed at the point of use. In summary though, we have used code from:

* `django-taggit <https://github.com/alex/django-taggit>`_
* `djangosnippets.org <https://github.com/coleifer/djangosnippets.org>`_
* `django-registration <https://bitbucket.org/ubernostrum/django-registration/>`_
* `django-avatar <https://github.com/ericflo/django-avatar>`_
* `Sphinx <http://sphinx.pocoo.org/latest/>`)

The jQuery Forms extensions is MIT licensed (compatible with BSD); more
information at http://malsup.com/jquery/form/

The Rss Feed icon is taken from Wikipedia and its licensed under GNU GPL v2, GNU LGPL v2.1, Mozilla Public License v1.1 and is described at https://en.wikipedia.org/w/index.php?title=File:Feed-icon.svg&oldid=453635063#License