.. _buildout-env:

===========================
Installazione con buildout
===========================

.. note:: Avvertenza

   Questa documentazione è qui per motivi storici. Attualmente facciamo il
   deploy usando docker e creiamo i docker nella continuous integration di
   heptapod quindi questi metodi sono usati solo in sistemi vecchi

Scopo del setup illustrato qui di seguito è:

* Creare un workflow in cui il setup di un sito sia fulmineo, almeno per
  quanto riguarda il lavoro umano...

* Creare una setup isolato e riproducibile. Le librerie utilizzate devono
  essere sotto stretto controllo del programmatore

* Deve essere possibile derogare se necessario (ad esempio non vogliamo
  ricompilare il modulo 'uno' necessario per collegarsi a Libreoffice)

Possibili alternative
======================

le alternative possibili sono

1. virtualenv_

2. buildout_ (ricca documentazione su pypi_)

Mentre virtualenv risulta particolarmente efficace per l'isolamento,
buildout risulta più pratico per la configurabilità. Noi useremo
``buildout`` costruito dentro un virtualenv. Entrambi richiedono di
compilare alcuni pacchetti quindi devono essere installati anche
alcuni pacchetti dev. Usiamo la versione buildout > 2.0, la versione
precedente utilizzava un sistema abbastanza differente/

Buildout plus
=============


Il motivo principale per cui sono a favore di buildout rispetto a pip
è che è molto più rigoroso nella verifica delle dipendenze.
Con ``pip`` se installo django==1.1.11 e poi installa django-cms==2.4
mi viene disinstallato django-1.1.11 in favore di uno più vecchio che
è un comportamento che spesso mi introduce errori.

Molte volte ci siamo trovati situazioni non riproducibili.

Il secondo motivo per cui assolutamente reputo che ``pip`` sia il male
è che non distingue fra pacchetti richiesti esplicitamente e
dipedenze. Questo problema dovrebbe essere affrontato da ``pipenv`` un
nuovo strumento che promette di essere più utile.


Buildout in pratica
===================

L'installazione di jumbo e dei siti che lo usano viene fatta usando
``buildout`` nel seguente modo::

   hg clone http://hg.thundersystems.it/siti/www.mysite.it
   cd www.mysite.it
   jmb-go -3Bd
   dj    # equivalente a bin/django shell = ./manage.py shell


Configurazioni una tantum
==========================

Questo semplice sistema prevede che siano state prese alcune precauzioni una
volta nel sistema (non per ogni pacchetto/sito) e che sia stato
personalizzato il sistema opportunamente. Il modo facile è installando il
pacchetto ``thunder-buildout`` dai repositori argo ma raccomando di leggere
anche :ref:`l'installazione manuale <buildout-manual>` dove spiego i vari componenti.

installazione tramite pacchetto deb
-----------------------------------

Occorre installare il pacchetto ``thunder-buildout`` che è un pacchetto che
contien pochi file ma molte dipendenze, ad esempio libreoffice che viene
usato in molti progetti per produrre le stampe.


Aggiungere la sorgente argodef::

     echo deb http://apt.argolinux.org precise main >> /etc/apt/sources.list
     wget -q -O - http://apt.argolinux.org/dists/stretch/public.key | sudo apt-key add -
     apt-get update
     apt-get install jmb


Attenzione che il pacchetto installa una situazione funzionante
comprensiva delle seguenti configurazioni:

   * configurazione in :file:`/root/.buildout` (leggi in seguito)

   * configurazione in :file:`/home/www` (leggi sotto)

   * fornisce i comandi

     :|dj|: interazione fondamental, equivalente a ``manage.py`` ma chiama
	   Python nell'ambiente virtuale corretto e può essere chiamato da
	   qualunque sottocartella del progetto. Utile anche per generare
	   documentazione e fare upload della stessa :ref:`dj` |dj|

     :|py|: chiama ip python dell ambiente virtuale

     :|ipy|:  chiama ipython dell'ambiente virtuale

     :|jmb-test-setup|: utile strumento per testate quali pacchetti sono
		       presenti nell'ambiente viutuale, generare i link ai
		       repositori (vedi sotto), manipolare i repo sotto ``.src``

     :|jmb-start|: starter di ogni applicazione. Crea un
		  progetto/applicazione nuovi a partire da un template che
		  viene tenuto costantemente aggiornato a come vogliamo che
		  siano i progetti/applicazioni

     :|jmb-prepare|: crea i pacchetti e cura l'upload nel nostro repository pipy_

     :|jmb-go|: una script che permette un avvio rapido di progetti

Struttura cartelle
===================

Il comandi riportati sopra (file:`python boostrap.py` e file:`bin/buildout`)
creano una struttura come la seguente::

  .
  |-- bin
  |    `--python         << eseguibile "isolato"
  |-- .develop-eggs       << egg-link ai sorgenti
  `-- .src
      |-- jmb.core    <<  codice sorgente (hg clone ...)
      |-- ...


mentre altre eggs saranno depositate nella cartella indicata nella
configurazionedi default ``~/.buildout/default.cfg``.

Sotto :file:`.src` troviamo tutti i sorgenti di cui è stato fatto il
checkout, ovvero quei sorgenti richiesti nella configurazione. È possibile
ed è lasciata libertà (dalla ricetta, non da me) di scegliere se sostituirlo
con un link simbolico. Spesso è la cosa più opportuna e per sostiture tutti
i link in un sol colpo potete usare il comando::

  jmb-test-setup -l


buildout.cfg
============

buildout usa "ricette" ed "estensioni" per implementare le cose che vogliamo
fare.  Le ricette che ho scelto puntano a:

.. _tl.buildout_virtual:

:creare un ambiente isolato:

  questo è compito di tl.buildout_virtual_python_, il compito è quello di
  fare in modo che il nostro ambiente non "veda" nessuna libreria di sistema
  in modo da essere sicuri che le librerie dichiarate in ``setup.py`` e in
  buildout.cfg siano le uniche necessarie.

.. _django-recipe:

:creare ambiente per django:

  questo è compito di djangorecipe_: crea un binario chiamato ``django``
  che è l'equivalente di ``manage.py`` ma che ha già impostato il path nel
  modo corretto: ogni volta che avremmo suato ``./manage.py`` suiamo questo
  in alternativa per avere un ``manage.py`` che opera sullo stesso ambiente
  virtuale. Ad esempio::

    bin/django test
    bin/django runserver
    bin/django shell

:usare i nostri sorgenti:

  questo è compito di mr.developer_. Buildout può lavorare in modo
  ``eggs`` o ``develop``. In sostanza per ogni libreria utilizzata
  verrà creata una voce di ``sys.path`` che punta ad una cartella egg.


Suggerisco di creare la configurazione iniziale con :ref:`jmb kick`, o
cookiecutter ma riporto un esempio di :file:`buildout.cfg` che non è
completo:

.. code-block:: ini

  [buildout]
  extends = thunder-buildout.cfg
  develop = .                  # dichiariamo la cartella corrente
                               # come cartella in sviluppo

  parts = req django ipython
  extensions = mr.developer
  auto-checkout = *
  sources-dir = .src

  [sources]
  # le sorgenti elencate qui sono automaticamnete messe
  # nelle develop-egg quindi disponibili senza bisogno di aggiungerle nelle egg
  jmb.core = hg ${thunder:jmb2}/jmb.core
  jmb.openvpn = hg ${thunder:jmb2}/jmb.openvpn

  [django]
  recipe = djangorecipe
  settings = tsettings
  eggs = django
  absolute_path = True


.. _setup.py:

PyCharm
--------


Per configurare PyCharm in modo che funzioni correttamente con
buildout:

* File -> Settings... ->Build, Execution, Deployment -> Buildout Support


* Abilitare il supporto per Buildout e come script utilizzare bin/ipython3
  che si trova nella cartella locale del progetto.

.. image:: ../images/pycharm.png
   :align: right


setup.py
=========

Tutto il sistema di packaging di Python si basa sulla configurazione
contenuta in ``setup.py`` in particolare nella direttive:

:name: nome del pacchetto (es.: jumbo-core)

:install_required:

   dipendenze esplicite del pacchetto::

      ['setuptools', 'xlwt', 'xlrd', 'django <= 1.2.7']


:packages:

   pacchetti messi a disposizione (es.: ['admin_tools',  'jumbo', ...])
   nella maggior parte dei casi va bene il default scritto nel template
   usato da :ref:`jmb-start`::

       packages=find_packages(exclude=['tests', 'tests.*'])

:version:

   è la versione di un pacchetto, indispensabile per potere fissare le rel
   che veramente funzionano

:package_data:

   sono i file che devono essere inclusi nel pacchetto anche se non sono
   moduli python: file css, js, html, png e txt. Oltre che qui vanno
   segnalati anche in MANIFEST.in. Il progetto di default mostra lesempio di
   come fare questo. Nel setup.py di default è inclusa la funzione
   ``get_data_files`` per facilitare l'inclusione degli stessi.


Una esauriente introduzione al setup può essere letta qui_


.. |dj| replace:: :ref:`dj`
.. |jmb-start| replace:: :ref:`jmb-start`
.. |jmb-go| replace:: :ref:`jmb-go`
.. |jmb-sync| replace:: :ref:`jmb-sync`
.. |jmb-prepare| replace:: :ref:`jmb-prepare`
.. |jmb-test-setup| replace:: :ref:`jmb-test-setup`
.. |ipy| replace:: :ref:`ipy`
.. |py| replace:: :ref:`py`
.. _tl.buildout_virtual_python: https://bitbucket.org/tlotze/tl.buildout_virtual_python/
.. _mr.developer: http://pypi.python.org/pypi/mr.developer
.. _virtualenv: http://www.virtualenv.org/en/latest/index.html
.. _buildout: http://www.buildout.org/
.. _buidldout_pypi: http://pypi.python.org/pypi/zc.buildout/1.5.2
.. _virtualenv: http://www.virtualenv.org/en/latest/index.html
.. _pypi: http://pypi.python.org/pypi/zc.buildout/1.5.2
.. _qui: http://docs.python.org/distutils/sourcedist.html
.. _pipy: http://pypi.thundersystems.it
.. _djangorecipe: http://pypi.python.org/pypi/djangorecipe/1.3