From de50c683bc80d6e342dc66d92337aaac86160d46 Mon Sep 17 00:00:00 2001 From: Martin Zimmermann Date: Thu, 20 Mar 2014 11:38:47 +0100 Subject: [PATCH] extend installation docs * add interludium for users new to Python * include guides for prebuilt packages and building from source (obsoletes DEVELOPMENT.md). --- docs/DEVELOPMENT.md | 59 --------------- docs/docs/install.rst | 168 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 166 insertions(+), 61 deletions(-) delete mode 100644 docs/DEVELOPMENT.md diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md deleted file mode 100644 index c5e38c3..0000000 --- a/docs/DEVELOPMENT.md +++ /dev/null @@ -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 - - -``` - - -Optimization ------------- - - ~> npm install -g requirejs uglifyjs - ~> make js - ~> # or r.js -o /isso/js/build.embed.js diff --git a/docs/docs/install.rst b/docs/docs/install.rst index 7efe8a7..b3cdb99 100644 --- a/docs/docs/install.rst +++ b/docs/docs/install.rst @@ -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 `_: ~> pip install isso -`Dont't have pip `_? +`Don't have pip? `_ .. 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 `__]. + + `#729218 `_ is a + ITP for Debian. To be officially packages by Debian, `#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 `__ and `Bower `__ + +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 + + + + +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):