README.rst
author David Douard <david.douard@logilab.fr>
Mon, 02 Jun 2014 14:56:01 +0200
changeset 2 a94559c3bff9
parent 0 5106aa7d0a28
child 10 f0ac4b0af639
permissions -rw-r--r--
[apt] move debian repo configurations in a 'logilab' package

========
cubicweb
========

Set up and configure the Cubicweb web application framework.

.. note::

    See the full `Salt Formulas installation and usage instructions
    <http://docs.saltstack.com/topics/conventions/formulas.html>`_.

Available states
================

.. contents::
    :local:

``cubicweb``
----------

Install Cubicweb from the system package manager. Note, the Cubicweb version
available varies by platform.

Example usage::

    include:
      - cubicweb

    mysite:
      git:
        - latest
        - name: git@git.example.com/mysite
        - target: /var/www/mysite
        - require:
            - pkg: cubicweb


Full-stack App Deployment
=========================

This formula also provides an example of how Salt can be used to deploy a
Cubicweb app in a single command, using the `OverState System`_. It installs
Cubicweb into a virtualenv, using pip with a requirements.txt.

.. _`OverState System`: http://docs.saltstack.com/ref/states/overstate.html

This example makes use of the following three files:

* `pillar.example`_ - Pillar data
* `overstate.single`_ - Single-host OverState deployment stages 
* `overstate.multi`_ - Multi-host OverState deployment stages

.. _pillar.example: https://github.com/saltstack-formulas/cubicweb-formula/blob/master/pillar.example
.. _overstate.single: https://github.com/saltstack-formulas/cubicweb-formula/blob/master/overstate.single
.. _overstate.multi: https://github.com/saltstack-formulas/cubicweb-formula/blob/master/overstate.multi

Deploying this example will require that the relevant files from above (the
Pillar data and appropriate OverState config file) are copied to the Master and
edited as necessary. The Pillar data will need to be available to all involved
minions.

Additionally, this example makes use of several other Salt formulae:

* `apache-formula`_
* `postgres-formula`_

.. _apache-formula: https://github.com/saltstack-formulas/apache-formula.git
.. _postgres-formula: https://github.com/saltstack-formulas/postgres-formula.git

To deploy the entire stack (Apache, PostgreSQL, Cubicweb, cubes) to a
single host, run the following command:

.. code-block:: bash

    # salt-run state.over deployment /path/to/overstate.single

To deploy using one database server, one Apache server and one or more
Cubiweb servers, run the following command:

.. code-block:: bash

    # salt-run state.over deployment /path/to/overstate.multi

.. note::

   If you did not create a separate ``deployment`` branch, then
   replace ``deployment`` with ``base`` in the above ``salt-run``
   commands.


Other Tips
==========

Create ``settings.py`` using data from Pillar
---------------------------------------------

The easiest way to create Cubicweb's ``setttings.py`` file using data from Pillar
is to simply transform a dictionary in YAML into a dictionary in Python.

``/srv/salt/mysite.sls``::

    include:
      - cubicweb.pip

    mysite:
      git:
        - latest
        - name: git@git.example.com/mysite
        - target: /var/www/mysite
        - require:
            - pip: cubicweb_pip

    mysite_settings:
      file:
        - managed
        - name: /var/www/mysite/settings.py
        - contents: |
            globals().update({{ salt['pillar.get']('mysite:settings') | python() | indent(8) }})
        - require:
          - git: mysite

``/srv/pillar/mysite.sls``::

    mysite:
      settings:
        ROOT_URLCONF: mysite.urls
        SECRET_KEY: 'gith!)on!_dq0=2l(otd67%#0urmrk6_d0!zu)i9fn=!8_g5(c'
        DATABASES:
          default:
            ENGINE: cubicweb.db.backends.mysql
            NAME: mysitedb
            USER: mysiteuser
            PASSWORD: mysitepass
            HOST: localhost
            PORT: 3306
        TEMPLATE_DIRS:
          - /var/www/mysite/cubicweb-tutorial/templates
        STATICFILES_DIRS:
          - /var/www/mysite/cubicweb-tutorial/static
        STATIC_ROOT: /var/www/mysite/cubicweb-tutorial/staticroot

Create ``settings.py`` with a template file
-------------------------------------------

A more traditional (and flexible) method of creating the ``settings.py`` file
is to actually create the file as a template.

``/srv/salt/mysite/mysite.sls``::

    include:
      - cubicweb.pip

    mysite:
      git:
        - latest
        - name: git@git.example.com/mysite
        - target: /var/www/mysite
        - require:
            - pip: cubicweb_pip

    mysite_settings:
      file:
        - managed
        - name: /var/www/mysite/settings.py
        - source: salt://mysite/files/settings-tmpl.py
        - template: jinja
        - require:
          - git: mysite

``/srv/salt/mysite/files/settings-tmpl.py``::

    {# Data can be defined inline, in Grains, in Pillar, etc #}

    {% set db_settings = {
        'default': {
            'ENGINE': 'cubicweb.db.backends.mysql',
            'HOST': 'localhost',
            'NAME': 'polldb',
            'PASSWORD': 'pollpass',
            'PORT': 3306,
            'USER': 'polluser',
        }
    } %}

    {% set staticfiles_dirs_settings = [
        '/var/www/poll/cubicweb-tutorial/static',
    ] %}

    {% set template_dirs_settings = [
        '/var/www/poll/cubicweb-tutorial/templates',
    ] %}

    ROOT_URLCONF = mysite.urls

    {# Have Salt automatically generate the SECRET_KEY for this minion #}
    SECRET_KEY = '{{ salt['grains.get_or_set_hash']('mysite:SECRET_KEY', 50) }}'

    DATABASES = {{ db_settings | python() }}

    TEMPLATE_DIRS = {{ template_dirs_settings | python() }}

    STATICFILES_DIRS = {{ staticfiles_dirs_settings | python() }}

    STATIC_ROOT = /var/www/mysite/cubicweb-tutorial/staticroot

Run ``syncdb`` or ``collectstatic`` automatically
-------------------------------------------------

A wait state can be used to trigger ``cubicweb-admin.py syncdb`` or
``cubicweb-admin.py collectstatic`` automatically. The following example runs
both commands whenever the Git repository containing the "mysite" Cubicweb
project is updated.

::

    include:
      - cubicweb.pip

    mysite:
      git:
        - latest
        - name: git@git.example.com/mysite
        - target: /var/www/mysite
        - require:
            - pip: cubicweb_pip

    mysite_syncdb:
      module:
        - wait
        - name: cubicweb.syncdb
        - settings_module: "mysite.settings"
        - bin_env: /path/to/virtualenv          # optional
        - pythonpath: /path/to/mysite_project   # optional
        - watch:
          - git: mysite

    mysite_collectstatic:
      module:
        - wait
        - name: cubicweb.collectstatic
        - settings_module: "mysite.settings"
        - bin_env: /path/to/virtualenv          # optional
        - pythonpath: /path/to/mysite_project   # optional
        - watch:
          - git: mysite