Installation
============

Isso is a web application written in Python. If pip and virtualenv mean
anything to you, continue with :ref:`install-from-pypi`. If you are running
Debian/Ubuntu or Gentoo, you can use :ref:`prebuilt-package`. If not, read the
next section carefully.

.. contents::
    :local:
    :depth: 1

Interludium: Python is not PHP
------------------------------

If you think hosting a web application written in Python is as easy as one
written in PHP, you are wrong. Unlike for PHP, many Linux distribution use
Python for internal tools. Your package manager already ships several python
libraries, but most likely not all required by Isso (or in an up-to-date
version – looking at you, Debian!).

That's why most Python developers use the `Python Package Index`_ to get their
dependencies. But the most important rule: never install *anything* from PyPi
as root. Not because of malicious software, but because you *will* break your
system.
``easy_install`` is one tool to mess up your system. Another package manager is
``pip``. If you ever searched for an issue with Python/pip and Stackoverflow is
suggesting your ``easy_install pip`` or ``pip install --upgrade pip`` (as root
of course!), you are doing it wrong. `Why you should not use Python's
easy_install carelessly on Debian`_ is worth the read.

Fortunately, Python has a way to install packages (both as root and as user)
without interfering with your globally installed packages: `virtualenv`. Use
this *always* if you are installing software unavailable in your favourite
package manager.

.. code-block:: sh

    # for Debian/Ubuntu
    ~> sudo apt-get install python-setuptools python-virtualenv

    # Fedora/Red Hat
    ~> sudo yum install python-setuptools python-virtualenv

The next steps should be done as regular user, not as root (although possible
but not recommended):

.. code-block:: sh

    ~> virtualenv /home/user/python/isso
    ~> source /home/user/python/isso/activate

After calling `source`, you can now install packages from PyPi locally into this
virtual environment. If you don't like Isso anymore, you just `rm -rf` the
folder. Inside this virtual environment, you may also execute the example
commands from above to upgrade your Python Package Manager (although it barely
makes sense), it is completely independent from your global system.

With a virtualenv active, you may now continue to :ref:`install-from-pypi`!
Of course you may not need a virtualenv when you are running dedicated virtual
machines or a shared host (e.g. Uberspace.de).

.. _Python Package Index: https://pypi.python.org/pypi
.. _Why you should not use Python's easy_install carelessly on Debian:
   https://workaround.org/easy-install-debian

.. _install-from-pypi:

Install from PyPi
-----------------

Requirements:

-  Python 2.6, 2.7 or 3.3+ (+ devel headers)
-  SQLite 3.3.8 or later
-  a working C compiler

Install Isso with `pip <http://www.pip-installer.org/en/latest/>`_:

.. code-block:: sh

    ~> pip install isso

`Don't have pip? <https://twitter.com/gardaud/status/357638468572151808>`_

.. code-block:: sh

    ~> easy_install isso  # cross your fingers

For easier execution, you can symlink the executable to a location in your
PATH:

.. code-block:: sh

    ~> ln -s /path/to/isso-venv/bin/isso /usr/local/bin/isso

To upgrade Isso, activate your virtual environment again, and run

.. code-block:: sh

    ~> pip install --upgrade isso

.. _prebuilt-package:

Prebuilt Packages
-----------------

* Debian: https://packages.crapouillou.net/ – built from PyPi. Includes
  startup scripts and vhost configurations for Lighttpd, Apache and Nginx
  [`source <https://github.com/jgraichen/debian-isso>`__].

  `#729218 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=729218>`_ is a
  ITP for Debian. To be officially packages by Debian, `#51
  <https://github.com/posativ/isso/issues/51>`_ needs to be done (contributions
  are welcome).

* Gentoo: http://eroen.eu/cgit/cgit.cgi/eroen-overlay/tree/www-apps/isso?h=isso
  – not yet available in Portage, but you can use the ebuild to build Isso.

* Arch Linux: https://aur.archlinux.org/packages/isso/ – built from PyPi.

Install from Source
-------------------

If you want to hack on Isso or track down issues, there's an alternate
way to set up Isso. It requires a lot more dependencies and effort:

- Python 2.6, 2.7 or 3.3+ (+ devel headers)
- Virtualenv
- SQLite 3.3.8 or later
- a working C compiler
- Node.js, `NPM <https://npmjs.org/>`__ and `Bower <http://bower.io/>`__

Get a fresh copy of Isso:

.. code-block:: sh

    ~> git clone https://github.com/posativ/isso.git
    ~> cd isso/

To create a virtual environment (recommended), run:

.. code-block:: sh

    ~> virtualenv .
    ~> source ./bin/activate

Install Isso and its dependencies:

.. code-block:: sh

    ~> python setup.py develop  # or `install`
    ~> isso run

Install JavaScript modules:

.. code-block:: sh

    ~> make init

Integration without previous optimization:

.. code-block:: html

    <script src="/js/config.js"></script>
    <script data-main="/js/embed" src="/js/components/requirejs/require.js"></script>

Optimization:

.. code-block:: sh

    ~> npm install -g requirejs uglifyjs jade
    ~> make js

.. _init-scripts:

Init scripts
------------

Init scripts to run Isso as a service (check your distribution's documentation
for your init-system; e.g. Debian uses SysVinit, Fedora uses SystemD) if you
don't use FastCGi or uWSGI:

-  SystemD: https://github.com/jgraichen/debian-isso/blob/master/debian/isso.service
-  SysVinit: https://github.com/jgraichen/debian-isso/blob/master/debian/isso.init
-  OpenBSD: https://gist.github.com/noqqe/7397719
-  Supervisor: https://github.com/posativ/isso/issues/47