186 lines
5.6 KiB
ReStructuredText
186 lines
5.6 KiB
ReStructuredText
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.
|
||
|
||
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
|