extend installation docs
* add interludium for users new to Python * include guides for prebuilt packages and building from source (obsoletes DEVELOPMENT.md).
This commit is contained in:
Martin Zimmermann
parent
e75fa4b7e1
commit
de50c683bc
@ -1,59 +0,0 @@
|
||||
Development
|
||||
===========
|
||||
|
||||
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.
|
||||
|
||||
Requirements:
|
||||
|
||||
- Python 2.6, 2.7 or 3.3
|
||||
- Ruby 1.8 or higher
|
||||
- Node.js, [NPM](https://npmjs.org/) and [Bower](http://bower.io/)
|
||||
|
||||
On Debian/Ubuntu install the following packages
|
||||
|
||||
~> sudo aptitude install python-setuptools python-dev npm ruby
|
||||
~> ln -s /usr/bin/nodejs /usr/bin/node
|
||||
|
||||
Get the repository:
|
||||
|
||||
~> git clone https://github.com/posativ/isso.git
|
||||
~> cd isso/
|
||||
|
||||
Install `virtualenv` and create a new environment for Isso (recommended):
|
||||
|
||||
~> pip install virtualenv
|
||||
~> virtualenv .
|
||||
~> source ./bin/activate
|
||||
|
||||
Install Isso dependencies:
|
||||
|
||||
~> python setup.py develop
|
||||
~> isso run
|
||||
|
||||
Compile SCSS to CSS:
|
||||
|
||||
~> gem install sass
|
||||
~> scss --watch isso/css/isso.scss
|
||||
|
||||
Install JS components:
|
||||
|
||||
~> make init
|
||||
~> # or cd isso/js && bower install almond requirejs requirejs-text
|
||||
|
||||
|
||||
Integration
|
||||
-----------
|
||||
|
||||
```html
|
||||
<script src="/isso/js/config.js"></script>
|
||||
<script data-main="/isso/js/embed" src="/isso/js/components/requirejs/require.js"></script>
|
||||
```
|
||||
|
||||
|
||||
Optimization
|
||||
------------
|
||||
|
||||
~> npm install -g requirejs uglifyjs
|
||||
~> make js
|
||||
~> # or r.js -o /isso/js/build.embed.js
|
||||
@ -1,5 +1,74 @@
|
||||
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
|
||||
packages. 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 ready, you may now continue to :ref:`install-from-pypi`!
|
||||
Note, that if you are using a slightly more advanced shared-hoster or virtual
|
||||
machines, you may not need virtual environments.
|
||||
|
||||
|
||||
.. _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:
|
||||
|
||||
@ -13,12 +82,107 @@ Install Isso with `pip <http://www.pip-installer.org/en/latest/>`_:
|
||||
|
||||
~> pip install isso
|
||||
|
||||
`Dont't have pip <https://twitter.com/gardaud/status/357638468572151808>`_?
|
||||
`Don't have pip? <https://twitter.com/gardaud/status/357638468572151808>`_
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
~> easy_install isso # cross your fingers
|
||||
|
||||
If you are using a virtualenv, you don't need to activate the environment
|
||||
every time you want to start Isso. 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 once 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)
|
||||
- SQLite 3.3.8 or later
|
||||
- a working C compiler
|
||||
- Ruby 1.8 or higher
|
||||
- SASS 3.0 or higher
|
||||
- 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
|
||||
|
||||
~> pip install virtualenv
|
||||
~> virtualenv .
|
||||
~> source ./bin/activate
|
||||
|
||||
Install Isso and its dependencies:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
~> python setup.py develop # or `install`
|
||||
~> isso run
|
||||
|
||||
Compilation from SCSS to CSS:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
~> make css
|
||||
|
||||
Install JavaScript modules:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
~> make init
|
||||
|
||||
Integration without previous optimzation:
|
||||
|
||||
.. 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
|
||||
~> make js
|
||||
|
||||
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):
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user