README.rst 4.77 KB
Newer Older
Denis Laxalde's avatar
Denis Laxalde committed
1
2
3
.. image:: https://travis-ci.org/logilab/saemref-formula.svg?branch=master
    :target: https://travis-ci.org/logilab/saemref-formula

Philippe Pepiot's avatar
init  
Philippe Pepiot committed
4
5
6
7
===============
saemref-formula
===============

8
9
A saltstack formula handling installation of `saem_ref`_.

10
11
12
13
14
15
The formula will run two web application server, one dedicated to OAIPMH
request to serve ``/oai`` on port 8081 and one for other requests on port 8080.

To use them in a single port you may configure a reverse proxy, such as apache2
or nginx, on front of the instances.

Philippe Pepiot's avatar
init  
Philippe Pepiot committed
16
17
18
19
20
21
Available states
================

.. contents::
    :local:

Philippe Pepiot's avatar
Philippe Pepiot committed
22
23
24
25
26
``saemref``
-----------

Equivalent to ``saemref.install`` and ``saemref.config``.

27
28
29
``saemref.install``
-------------------

Philippe Pepiot's avatar
Philippe Pepiot committed
30
31
32
33
34
35
36
37
Installs the saemref package from logilab repositories and create an instance
for user ``saemref``.

Cubicweb config files are located in ``~saemref/etc/cubicweb.d/saemref`` and
``cubicweb-ctl`` can be invoked as user ``saemref`` with environment variable
``CW_MODE=user``.

The state require the installation of `epel-formula`_ and `postgres-formula`_
38
with version 9.4 (see ``pillar.example``).
39
40
41
42

``saemref.config``
------------------

Philippe Pepiot's avatar
Philippe Pepiot committed
43
44
45
46
47
Only manage instance configuration files.

``saemref.db-create``
---------------------

48
49
Create instance database with ``cubicweb-ctl db-create`` (call implicitly ``db-init``).

50
51
WARNING: this will destroy existing database if exists.

52
53
54
55
``saemref.db-init``
---------------------

Initialize instance database schema with ``cubicweb-ctl db-init``.
56
57
58
59
60

``saemref.supervisor``
----------------------

Install and manage `supervisor`_ configuration for the saemref installation.
61
62
63
64
Here is some useful commands:

- restart instance: ``supervisorctl restart saemref``
- restart supervisor: ``systemctl restart supervisord``
65

Philippe Pepiot's avatar
Philippe Pepiot committed
66

67
68
69
70
71
Requirements
============

If using postgres as database driver, ensure the `postgres contrib`_ package is
installed on server side.
Philippe Pepiot's avatar
Philippe Pepiot committed
72

73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
Recomended usage
================

Given target minion_id is 'srv'.

/srv/salt/top.sls::

    base:
        'srv':
            - saemref
            - saemref.supervisor


/srv/pillar/top.sls::

    base:
        'srv':
            - saemref


/srv/pillar/saemref.sls: see `pillar.example <test/pillar/example.sls>`_


Example of reverse proxy configuration for nginx::

    server {
        listen 80;
        server_name saemref.example.com;
        location / {
            proxy_pass http://srv:8080;
        }
        location /oai {
            proxy_pass http://srv:8081;
        }
    }


For the first installation run ``salt srv state.sls db-create`` to create
the database (WARNING: this will destroy existing database if exists).

Then run: ``salt srv state.highstate`` to finish the installation.
114

115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
Upgrades
========

To force an upgrade to the latest version of saem-ref, connect to the minion as
root, then run::

    [root@minion] % supervisorctl stop all
    [root@minion] % salt-call state.sls saemref.install pillar='{"upgrade": true}'
    # be patient
    [root@minion] % su - saemref
    [saemref@minion] % . venv/bin/activate
    (venv) [saemref@minion] % cubicweb-ctl upgrade saemref
    # proceed to the cubicweb upgrade process
    (venv) [saemref@minion] % exit
    [root@minion] % supervisorctl start all

131
132
133
134
135
136
Testing
=======

The script `run-test.py` can help to develop and test the formula using
`docker`_ and `testinfra`_.

Sylvain Thenault's avatar
Sylvain Thenault committed
137
138
The command ``./run-test.py dev centos7`` will build image from
``test/centos7.Dockerfile`` and span a shell in a new container with mounted
139
140
141
volumes from the host (so you can develop formula on the host and test it in
the container with ``salt-call``).

Sylvain Thenault's avatar
Sylvain Thenault committed
142
The command ``./run-test.py dev centos7 --salt`` is the same as above but will
143
144
provision the container (eg. calling ``salt-call state.highstate``)

Sylvain Thenault's avatar
Sylvain Thenault committed
145
The command ``./run-test.py test centos7`` built a provisioned image
146
147
148
(highstate) and run testinfra tests on it.

Note that you can add any parameters that testinfra (pytest) accept, for
Sylvain Thenault's avatar
Sylvain Thenault committed
149
instance ``./run-test.py test centos7 -- -k idempotence --pdb``.
150

Philippe Pepiot's avatar
init  
Philippe Pepiot committed
151

Philippe Pepiot's avatar
Philippe Pepiot committed
152
153
154
155
156
157
158
159
160
161
162
163
Testing migration
=================

Add dumps generated by ``cubicweb-ctl db-dump`` in the ``test/dumps`` directory, then::

    # To test upgrade against latest public changeset of http://hg.logilab.org/master/cubes/saem_ref
    ./run-tests.py test centos7 -- test/test_migration.py --upgrade-revision master

    # To test against any revision from http://hg.logilab.org/review/cubes/saem_ref
    ./run-tests.py test centos7 -- test/test_migration.py --upgrade-revision REV


164
165
166
167
.. _saem_ref: https://www.cubicweb.org/project/cubicweb-saem_ref
.. _supervisor: http://supervisord.org
.. _docker: https://www.docker.com/
.. _testinfra: https://testinfra.readthedocs.org/
Philippe Pepiot's avatar
Philippe Pepiot committed
168
169
.. _epel-formula: https://github.com/saltstack-formulas/epel-formula
.. _postgres-formula: https://github.com/saltstack-formulas/postgres-formula
170
.. _postgres contrib: https://www.postgresql.org/docs/current/static/contrib.html