Documentation is now exhaustive and zerobin is apache friendly

Author: sametmax

docs/.build/doctrees/en/apache_install.doctree

@@ -2,8 +2,7 @@
 Apache setup
 =============
 
-Apache is slower, heavier and more complicated to setup than Nginx. But it's also
-much more famous:
+Apache is heavier than Nginx. But it's also much more famous:
 
 - more people will be able to help you on forums;
 - your hosting will most probably support Apache;
@@ -33,7 +32,65 @@ the setup of the Apache module mod_wsgi. If you don't know how to do this, or
 if you can't do it (E.G: your hosting won't let you), you need to go for
 the CGI setup.
 
-==========
+First, make sure you have mod_wsgi installed and enable by running (as admin)::
+
+    a2enmod wsgi
+
+This enable mod_wsgi. It it doesn't, install it first (on ubuntu, the package
+is libapache2-mod-wsgi).
+
+Then create an Apache configuration file, usually in /etc/apache/sites-available/.
+Name it zerobin::
+
+    <VirtualHost *:80>
+        ServerName www.yourwebsite.com
+
+        WSGIDaemonProcess zerobin user=www-data group=www-data processes=1 threads=5
+        WSGIScriptAlias / /path/to/zerobin/app.wsgi
+
+        <Directory /path/to/zerobin/zerobin/>
+            WSGIProcessGroup zerobin
+            WSGIApplicationGroup %{GLOBAL}
+            Order deny,allow
+            Allow from all
+        </Directory>
+    </VirtualHost>
+
+Activate the website (as admin)::
+
+    a2ensite zerobin
+
+And reload the apache configuration (as admin)::
+
+    service apache2 reload
+
+You'll note that we refer to a file named app.wsgi. It's a Python file
+creating the application Apache is going to use to start the Python process::
+
+    import os, sys
+
+    # make sure the zerobin module is in the PYTHON PATH and importable
+    ZEROBIN_PARENT_DIR = os.path.dirname(os.path.dirname(__file__))
+    sys.path.insert(0, ZEROBIN_PARENT_DIR)
+
+    # create the wsgi callable
+    from zerobin.routes import get_app
+    settings, application = get_app(compressed_static=True)
+
+You can of course create your own, as the `get_app` function is the only
+way to pass settings to 0bin with this setup. You would do this by creating
+a configuration file and passing it to the function::
+
+    import os, sys
+
+    ZEROBIN_PARENT_DIR = '/path/to/zerobin/parent/dir'
+    sys.path.insert(0, ZEROBIN_PARENT_DIR)
+
+    from zerobin.routes import get_app
+    settings, application = get_app(settings_file='/path/to/settings.py')
+
+CGI
+===
 
-This setup is considered as slow, but you will still benefit from Apache
-robustness.
+You can also run 0bin using CGI, but infortunaly we didn't have time to cover
+it yet. Please contact us if you ever get the need to use it.

docs/.build/doctrees/en/nginx_install.doctree

@@ -51,9 +51,51 @@ installing it.
 Vous must create a Nginx configuration file for 0bin. On GNU/Linux, they usually
 go into /etc/nginx/conf.d/. Name it zerobin.conf.
 
-The minimal file to run the site is:
-
-But you can make some adjustement to get better perfomances:
+The minimal configuration file to run the site is::
+
+    server {
+        listen       80;
+        server_name www.yourwebsite.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:8000;
+        }
+    }
+
+`proxy_pass` just passes the external request to the Python process.
+The port much match the one used by the 0bin process of course.
+
+You can make some adjustements to get a better user experience::
+
+    server {
+        listen       80;
+        server_name www.yourwebsite.com;
+
+        location /favicon.ico {
+            root  /path/to/zerobin/static/img;
+        }
+
+        location /static/ {
+            root  /path/to/zerobin;
+            gzip  on;
+            gzip_http_version 1.0;
+            gzip_vary on;
+            gzip_comp_level 6;
+            gzip_proxied any;
+            gzip_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript;
+            gzip_buffers 16 8k;
+            # Disable gzip for certain browsers.
+            gzip_disable ~@~\MSIE [1-6].(?!.*SV1)~@~];
+            expires modified +90d;
+        }
+
+        location / {
+            proxy_pass http://zerobin_cherrypy;
+        }
+    }
+
+This make Nginx serve the favicon and static files, set the expire HTTP headers
+and make sure gzip compression is used with browsers that support it.
 
 
 

docs/.build/doctrees/en/options.doctree

@@ -1,15 +1,3 @@
-
-
---host=STR
-
-The host on which to listen for incomming request. Usually 127.0.0.1 to
-listen locally or 0.0.0.0 to listen from the outside.
-
-Default: 127.0.0.1
-Setting file : HOST
-
-
-
 ============
 Options
 ============

docs/.build/doctrees/en/theming.doctree

@@ -2,9 +2,9 @@
 Theming
 =======
 
-0bin comes a complete theming support, but for now it's not well ingrated.
+0bin comes with a complete theming support, but for now it's not well integrated.
 
-If you wish to create your own theme, you'll need to create template similar
+If you wish to create your own theme, you'll need to create templates similar
 to the ones in zerobin/view, and add the path to the director containing them
 to the settings file.
 

docs/.build/doctrees/en/using_supervisor.doctree

@@ -1,3 +1,72 @@
-====================
+=================
 Using supervisor
-====================
+=================
+
+Supervisor is a very nice way to manage you Python processes. We won't cover
+the setup (which is just apt-get install supervisor or pip install supervisor
+most of the time), but here is a quick overview on how to use it.
+
+Create a configuration file named supervisor.ini::
+
+    [unix_http_server]
+    file=/tmp/supervisor.sock;
+
+    [supervisorctl]
+    serverurl=unix:///tmp/supervisor.sock;
+
+    [rpcinterface:supervisor]
+    supervisor.rpcinterface_factory=supervisor.rpcinterface:make_main_rpcinterface
+
+    [supervisord]
+    logfile=/tmp/zerobin.log
+    logfile_maxbytes=50MB
+    logfile_backups=2
+    loglevel=trace
+    pidfile=/tmp/supervisord.pid
+    nodaemon=false
+    minfds=1024
+    minprocs=200
+    user=zerobin
+
+    [program:zerobin]
+    command=/path/to/zerobin/zerobin.py --port 80 --compressed-static
+    directory=/path/to/zerobin/
+    environment=PYTHONPATH='/path/to/zerobin/'
+    user=zerobin
+    autostart=true
+    autorestart=true
+
+The 4 first entries are just boiler plate to get you started, you can copy
+them verbatim.
+
+The last one define one (you can have many) process supervisor should manage.
+
+It means it will run the command::
+
+     /path/to/zerobin/zerobin.py --port 80 --compressed-static
+
+In the directory, with the environnement and the user you defined.
+
+This command will be ran as a daemon, in the background.
+
+`autostart` and `autorestart` just make it fire and forget: the site will always be
+running, even it crashes temporarly or if you retart the machine.
+
+The first time you run supervisor, pass it the configuration file::
+
+    supervisord -c /path/to/supervisor.ini
+
+Then you can manage the process by running::
+
+    supervisorctl -c /path/to/supervisor.ini
+
+It will start a shell from were you can start/stop/restart the service
+
+You can read all errors that might occurs from /tmp/zerobin.log.
+
+.. Note::
+
+    If you installed zerobin in a virtualenv, you may set the command
+    to run directly from it::
+
+        command=/path/to/virtualenv/bin/zerobin --port 80 --compressed-static

docs/.build/doctrees/environment.pickle

@@ -2,8 +2,7 @@
 Installation avec Apache
 =========================
 
-Apache est plus lent, plus lourd, et plus complexe à mettre en oeuvre que Nginx.
-Mais il est aussi beaucoup plus connu:
+Apache est plus lourd que Nginx mais il est aussi beaucoup plus connu:
 
 - plus de gens pourront vous aider les fora;
 - votre hébergeur propose surement Apache;
@@ -34,9 +33,67 @@ l'installation du modle Apache mod_wsgi. Si vous ne savez pas comment faire,
 ou si vous ne pouvez pas le faire (par exemple sur un hébergement mutualisé
 qui ne le propose pas), il vous faudra choisir l'installation CGI.
 
+Premièrement, assurez-vous d'avoir mod_wsgi installé et chargé (en tant qu'admin)::
 
-Mod_CGI
-==========
+    a2enmod wsgi
+
+Ceci va activer mod_wsgi. Si cela ne marche pas, il faudra l'installer d'abord (
+sur ubuntu, le paquet est libapache2-mod-wsgi)
+
+Ensuite, il faut créer un fichier de configuration Apache, généralement dans
+/etc/apache/sites-available/. Nommez le zerobin::
+
+    <VirtualHost *:80>
+        ServerName www.votersiteweb.com
+
+        WSGIDaemonProcess zerobin user=www-data group=www-data processes=1 threads=5
+        WSGIScriptAlias / /chemin/vers/zerobin/app.wsgi
+
+        <Directory /chemin/vers/zerobin/>
+            WSGIProcessGroup zerobin
+            WSGIApplicationGroup %{GLOBAL}
+            Order deny,allow
+            Allow from all
+        </Directory>
+    </VirtualHost>
+
+Activez le site web (en tant qu'admin)::
+
+    a2ensite zerobin
+
+Et rechargez la configuration d'Apache (en tant qu'admin)::
+
+    service apache2 reload
+
+Vous aurez noté que l'on fait référence à un fichier nommé app.wsgi. C'est un
+fichier Python qui créé l'application qu'Apache va utiliser pour lancer le
+processus Python::
+
+    import os, sys
+
+    # s'assurer que le module zerobin est dans le PYTHON PATH et importable
+    ZEROBIN_PARENT_DIR = os.path.dirname(os.path.dirname(__file__))
+    sys.path.insert(0, ZEROBIN_PARENT_DIR)
+
+    # créer le wsgi callable
+    from zerobin.routes import get_app
+    settings, application = get_app(compressed_static=True)
+
+Vous pouvez bien sûr créer le votre, puisque la fonction `get_app` et le seul
+moyen de passer des paramètres à 0bin avec cette installation. Cela peut se
+faire en créant un fichier de configuration et en le passant à la fonction::
+
+    import os, sys
+
+    ZEROBIN_PARENT_DIR = '/chemin/du/dossier/parent/de/zerobin'
+    sys.path.insert(0, ZEROBIN_PARENT_DIR)
+
+    from zerobin.routes import get_app
+    settings, application = get_app(settings_file='/path/to/settings.py')
+
+CGI
+===
+
+Vous pouvez aussi utiliser CGI, mais nous n'avons pas encore eu le temps de
+couvrir cette partie. Contactez nous si vous avez besoin de l'utiliser.
 
-Cette installation est considérée comme relativement lente. Mais vous bénéficierez
-tout de même de la robustesse d'Apache

docs/.build/doctrees/fr/apache_install.doctree

@@ -55,10 +55,53 @@ nous ne couvrirons pas cette partie.
 Vous devez créer une fichier de configuration Nginx pour 0bin. Sous GNU/Linux,
 on les mets en général dans /etc/nginx/conf.d/. Nommez le zerobin.conf.
 
-Le fichier minimal pour faire tourner le site est:
-
-Mais on peut apporter plusieurs améliorations de performance:
-
+Le fichier de configuration minimal pour faire tourner le site est::
+
+    server {
+        listen       80;
+        server_name www.votresiteweb.com;
+
+        location / {
+            proxy_pass http://127.0.0.1:8000;
+        }
+    }
+
+`proxy_pass` transmet les requêtes aux processus Python. Bien entendu le
+port doit correspondre à celui utilisé par 0bin.
+
+On peut apporter plusieurs améliorations à l'expérience utilisateur::
+
+    server {
+        listen       80;
+        server_name www.votresiteweb.com;
+
+        location /favicon.ico {
+            root  /chemin/vers/zerobin/static/img;
+        }
+
+        location /static/ {
+            root  /chemin/vers/zerobin;
+            gzip  on;
+            gzip_http_version 1.0;
+            gzip_vary on;
+            gzip_comp_level 6;
+            gzip_proxied any;
+            gzip_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript;
+            gzip_buffers 16 8k;
+            # Disable gzip for certain browsers.
+            gzip_disable ~@~\MSIE [1-6].(?!.*SV1)~@~];
+            expires modified +90d;
+        }
+
+        location / {
+            proxy_pass http://zerobin_cherrypy;
+        }
+    }
+
+Nginx sert maintenant le favicon ainsi que les fichiers statiques,
+on a ajouté une date d'expiration dans les en-têtes HTTP
+et on s'assure que la compression gzip est utilisée pour les navigateurs
+qui la supporte.