summaryrefslogtreecommitdiffstats
path: root/README
blob: c73ed220a9fa27f6dcedc4d6ae936651b48d93c5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
Hobo
====

Administration portal to configure and deploy applications.


Installation
------------

Dependencies can be installed with pip,

 $ pip install -r requirements.txt

It's then required to get the database configured (./manage.py syncdb); by
default it will create a db.sqlite3 file.

Hobo can then be run like typical django applications (./manage.py runserver),
it will communicate to deployment agents using Celery and expects a running
RabbitMQ server running on localhost.

The agent in charge of deploying application can then be run on the application
servers, for example:

  celery --app=hobo.agent.worker worker --loglevel=info

The agent will use settings from the file declared in the HOBO_AGENT_SETTINGS_FILE
environment variable (examples in hobo/agent/worker/settings.py)


Configuration
-------------

Hobo server configuration take place in hobo/settings.py, which import local
settings from the file declared in the HOBO_SETTINGS_FILE environment variable.

Adapt BROKER_URL if RabbitMQ doesn't run on localhost.

Some applications may support deployments templates, they can be specified in
the configuration with the SERVICE_TEMPLATES variable.

  SERVICE_TEMPLATES = {
        'wcs': [('export-auquo-light.wcs', u'Au quotidien light'),
                ('export-auquo.wcs', u'Au quotidien'),
                ('export-demo.wcs', u'Démo au quotidien')
                ],
  }


Agent configuration
-------------------

Agent configuration take place in hobo/agent/worker/settings.py, which import
local settings from the file declared in the HOBO_AGENT_SETTINGS_FILE
environment variable.

It's possible to limit agents to particular applications, or particular
hostnames, using the AGENT_HOST_PATTERNS configuration variable.

The format is a dictionary with applications as keys and a list of hostnames as
value. The hostnames can be prefixed by an exclamation mark to exclude them.

  AGENT_HOST_PATTERNS = {
     'wcs': ['*.example.net', '!  *.dev.example.net'],
  }

Will limit wcs deployments to *.example.net hostnames, while excluding
*.dev.example.net.


Usage
-----

Go to environment settings, pick a service, fill its name and URL, and watch it
being deployed.  Successfully deployed services will add a link to their
administration pages on the homepage.


Environment
-----------

An Hobo agent is a class defined in `hobo.agent.worker.services` and derived from
`BaseService`. For each service in the environment dictionary sent by the hobo
portal, it's instantiated with the key `base_url`, `title` and `secret_key` of
the service. If the `base_url` matches the `AGENT_HOST_PATTERNS` locally
defined, the `execute()` method of the instant is called, passing it the full
environment dictionary.

The environment dictionary contains services for this particular agent and all
other services defined on the portal. The `execute()` method should only create
a tenant for the service whose `base_url` was passed to constructor. All other
informations are only for defining links with other services. The schema of the
dictionary is::

    {
        'timestamp': <current_time_as_an_unix_timestamp>,
        'users': [
            {
                'username': 'john.doe',
                'first_name': 'John',
                'last_name': 'Doe',
                'email': 'john.doe@example.com',
                'password': '<django-compatible-hashed-password>',
            }
        ],
        'services': [
           {
                'service-id': 'authentic' / 'wcs' / 'passerelle',
                'service-label': 'Authentic' / 'w.c.s.' / 'Passerelle',
                'title': 'name of service,
                'secret_key': '..', # base secret for Django applications or other needs
                'base_url': 'base url of the service',
                'saml-sp-metadata-url': '...',
                'template_name': 'demo', # name of the template bundle to use
                'variables': {
                    'variable-1': 'value-of-variable-1'
                }
           }
        ],
        'fields': [
           {
               'disabled': boolean,
               'name': unique identifier (e.g. 'first_name'),
               'label': '..' (e.g. 'First Name'),
               'kind': 'title' / 'string' / 'email',
               'asked_on_registration': boolean,
               'user_editable': boolean,
               'required': boolean,
               'user_visible': boolean,
               'order': 1
           },
        ],
        'variables': {
            'variable-1': 'value-of-variable-1'
        }
    }

Agents
------

 - w.c.s.

w.c.s. instances will be deployed using "/usr/bin/wcsctl" by default, this
command can be adapted in the WCS_MANAGE_COMMAND setting. It should be run
with the same rights as the wcs process (redefine the command to use sudo
if necessary).

Template keys defined in SERVICE_TEMPLATES have to map wcs skeleton sites
(created from settings / export) stored in /var/lib/wcs/skeletons (the exact
directory may vary according to the wcs configuration).

 - authentic2

authentic2 instances will be deployed using
"/usr/bin/authentic2-multitenant-manage" by default, this command can be
adapted in the AUTHENTIC_MANAGE_COMMAND setting.  It should be run with the
same rights as the authentic2 process (redefine the command to use sudo if
necessary).

The agent also provide a commands to import roles from w.c.s named
import-wcs-roles. It computes the web-service credentials from the hobo.json
and use the email of the oldest superuser. Cron job can be created for calling
this command when regular synchronization of roles with your w.c.s.  instances
is needed. The sole option named "--delete" indicate if you want to delete
stale roles, default is to not delete them.  

Tests
-----

For testing hobo server, do in a virtualenv:

   pip install pytest pytest-django

   DJANGO_SETTINGS_MODULE=hobo.settings HOBO_SETTINGS_FILE=tests/settings.py py.tests tests

For testing multitenant framework, do in a virtualenv:

   pip install pytest pytest-django memcached mock .

   cd tests_multitenant ; PYTHONPATH=. DJANGO_SETTINGS_MODULE=settings py.test .